rng

R2026b

Control random number generator

Syntax

rng("default")

rng(seed)

rng(seed,generator)

rng(generator)

rng(sprev)

s = rng

s = rng(___)

Description

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.

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)

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

s = rng returns the current random number generator settings in a structure s with fields Type, Seed, and State.

s = rng(___) sets the random number generator settings using the specified arguments and returns the previous settings in a structure s. You can specify the output argument with any of the input argument combinations in the previous syntaxes.

Examples

Use Default Generator Settings

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 uses the Mersenne Twister algorithm with seed 0.

s = rng

s = struct with fields:
     Type: 'twister'
     Seed: 0
    State: [625×1 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 Settings Window. If you do not change the MATLAB settings, then rng uses the factory value of "twister" for the Mersenne Twister algorithm with seed 0, as in previous releases.

Set and Restore Generator Settings

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: [625×1 uint32]

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

r = rand(1,5)

r = 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")
rnew = rand(1,5)

rnew = 1×5

    0.5361    0.2319    0.7753    0.2390    0.0036

Now restore the previous generator settings and create a random vector. The result matches the first row vector r that you created with the previous generator.

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

rprev = 1×5

    0.4360    0.0259    0.5497    0.4353    0.4204

Input Arguments

seed — Random number generator seed

nonnegative integer | "shuffle"

Random number generator 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.

generator — Random number generator algorithm

"twister" (default) | "combRecursive" | "multFibonacci" | "pcg" | "philox" | "simdTwister" | "threefry" | "xoshiro"

Random number generator algorithm, specified as one of the generator names in the table. For more information on the generator algorithms, see Create and Control Random Number Streams.

Name	Description
"twister" (default)	Mersenne Twister
"combRecursive"	Combined multiple recursive generator
"multFibonacci"	Multiplicative lagged Fibonacci generator
"pcg" (since R2026b)	64-bit permuted congruential generator with double xor-shift multiply
"philox"	Philox 4x32 generator with 10 rounds
"simdTwister"	SIMD-oriented fast Mersenne Twister
"threefry"	Threefry 4x64 generator with 20 rounds
"xoshiro" (since R2026b)	Xor-shift-rotate generator with 256-bit state and double addition

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

Name	Description
"v4"	Legacy MATLAB version 4.0 generator
"v5normal"	Legacy MATLAB version 5.0 normal generator
"v5uniform"	Legacy MATLAB version 5.0 uniform generator

sprev — Previous random number generator settings

structure

Previous random number generator settings, specified as a structure with fields Type, Seed, and State. The structure sprev must be a structure that is returned by a previous call to s = rng or s = rng(__).

Output Arguments

s — Random number generator settings

structure

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

More About

Default Settings for Random Number Generator

• You can change the default algorithm and seed for the random number generator from the MATLAB Settings window. On the Home tab, in the Environment section, click Settings. 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 setting. (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 settings. If you do not change the Random Number Generation setting, then rng uses the factory value of "twister" for the Mersenne Twister generator with seed 0, as in previous releases.

• If you call rng("default") on parallel workers (requires Parallel Computing Toolbox™), rng initializes the Threefry 4x64 generator with 20 rounds and a seed value of 0, and assigns an independent stream to each worker running the same job.

  Changing the default generator settings in the MATLAB Settings 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 settings. However, this command does not guarantee the same results between different MATLAB sessions with different settings.

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 settings. For example, use rng("twister") to use the Mersenne Twister generator with seed 0.

Pseudorandom Number Generator

The rng function is a pseudorandom number generator, which creates a deterministic sequence of numbers that appear random. These numbers are predictable if the seed and the deterministic algorithm of the generator are known. While not truly random, the generated numbers pass various statistical tests of randomness, satisfying the independent and identically distributed (i.i.d.) condition, and justifying the name pseudorandom.

Tips

• When you perform parallel processing with Parallel Computing Toolbox, 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 settings 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).

• The rng function controls random number generation for in-memory MATLAB arrays. To control random number generation for tall arrays, use tallrng. To control random number generation on the GPU, use gpurng (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.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Thread-Based Environment

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

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

Version History

Introduced in R2011a

R2026b: Generate random numbers using two new algorithms: "pcg" and "xoshiro"

You can use two new algorithms for random number generation: "pcg" and "xoshiro". To select these generator algorithms when controlling the MATLAB random number generator using rng, specify the generator name, such as rng("pcg") or rng("xoshiro"). You can also set either generator as the default by specifying it in the MATLAB Settings Window.

R2023b: Specify random number algorithm without specifying seed

Use the new syntax rng(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 rng uses a seed of 0. This syntax is equivalent to rng(0,generator). For example, rng("philox") initializes the Philox 4x32 generator with a seed of 0.

R2023b: Change default algorithm and seed for random number generator

You can change the default algorithm and seed for the random number generator from the MATLAB Settings Window. On the Home tab, in the Environment section, click Settings. 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 setting.

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 settings. If you do not change the Random Number Generation setting, then rng uses the factory value of "twister" for the Mersenne Twister generator with seed 0, as in previous releases.

To access and modify settings for the random number generator programmatically, you can access the matlab.general.randomnumbers settings using the root SettingsGroup object returned by the settings function. For example, show the default algorithm and seed that you have set for the random number generator.

s = settings;
s.matlab.general.randomnumbers.DefaultAlgorithm
s.matlab.general.randomnumbers.DefaultSeed

When you perform parallel processing (requires Parallel Computing Toolbox), by default, the MATLAB client uses the Mersenne Twister random number 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 Settings window or using the matlab.general.randomnumbers settings affects only the default behavior of the client and does not affect the default behavior of the parallel workers.

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 4x64 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.