tallrng

Control random number generation for tall arrays

Syntax

tallrng("default")

tallrng("shuffle")

tallrng(seed)

tallrng(seed,generator)

tallrng("shuffle",generator)

tallrng(generator)

state = tallrng

tallrng(state)

Description

tallrng("default") restores the settings of the random number generator used in tall array calculations to their default values. The random numbers produced are the same as if you restart MATLAB^®.

tallrng("shuffle") specifies the seed of the random number generator based on the current time. Use this syntax when you want different sequences of random numbers each time they are generated.

tallrng(seed) specifies the starting point, or seed, of the random number generator. Use this syntax when you want to produce predictable sequences of numbers.

tallrng(seed,generator) or tallrng("shuffle",generator) also specifies the algorithm for the random number generator to use. For example, tallrng(0,"mlfg6331_64").

tallrng(generator) specifies the algorithm for the random number generator to use with a seed of 0. This syntax is equivalent to tallrng(0,generator). (since R2023b)

state = tallrng returns the current state of the random number generator as a structure. Use the structure to restore the random number generator to the captured state at a later time with tallrng(state).

tallrng(state) restores the state of the random number generator using settings previously captured with state = tallrng.

Note

The default algorithm and seed for the random number generator in the MATLAB Preferences window only affect rng("default") and do not affect calls to tallrng("default).

Examples

Capture and Restore Generator Settings

Capture the generator settings, generate an array of random numbers, and then restore the generator to the initial settings to create predictable arrays of random numbers.

Save the current state of the random number generator.

state = tallrng

state = struct with fields:
           Type: 'threefry'
           Seed: 0
    StreamIndex: 1
      Substream: 1

Create a tall array of random numbers using arrayfun.

t = tall(zeros(10,1));
n1 = arrayfun(@(x) x+randn, t);
n1 = gather(n1)

Evaluating tall expression using the Local MATLAB Session:
- Pass 1 of 2: Completed in 1 sec
- Pass 2 of 2: Completed in 0.22 sec
Evaluation completed in 1.9 sec

n1 = 10×1

   -0.3479
    0.1057
    0.3969
    0.6544
   -1.8228
   -1.1037
    0.4521
    1.4768
    0.0832
   -1.2005

Restore the generator to the previous state and regenerate the array of random numbers. The two arrays n1 and n2 are equal.

tallrng(state)
n2 = arrayfun(@(x) x+randn, t);
n2 = gather(n2)

Evaluating tall expression using the Local MATLAB Session:
- Pass 1 of 2: Completed in 0.22 sec
- Pass 2 of 2: Completed in 0.15 sec
Evaluation completed in 0.64 sec

n2 = 10×1

   -0.3479
    0.1057
    0.3969
    0.6544
   -1.8228
   -1.1037
    0.4521
    1.4768
    0.0832
   -1.2005

Input Arguments

seed — Random number seed

0 (default) | nonnegative integer

Random number seed, specified as a nonnegative integer. The seed specifies the starting point for the algorithm to generate random numbers. Specify the seed when you want reproducible results.

The maximum value of the seed is 232-1.

Example: tallrng(3)

generator — Random number algorithm

"threefry" (default) | "multFibonacci" | "philox" | "combRecursive"

Random number algorithm, specified as one of the options in this table. You can specify the regular or convenience name.

Name	Convenience Name	Description
"threefry4x64_20" (default)	"threefry"	Threefry 4x64 generator with 20 rounds
"mrg32k3a"	"combRecursive"	Combined multiple recursive generator
"mlfg6331_64"	"multFibonacci"	Multiplicative lagged Fibonacci generator
"philox4x32_10"	"philox"	Philox 4x32 generator with 10 rounds

tallrng supports random number generators that have multiple stream and substream support. See Creating and Controlling a Random Number Stream for a complete list of available generators in MATLAB.

Example: tallrng(0,"mlfg6331_64")

state — Previous random number generator state

structure

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

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

Data Types: struct

Output Arguments

state — Random number generator state

structure

Random number generator state, returned as a structure with these fields.

Field	Description	Example Value
Type	Type of random number generator	'threefry'
Seed	Number indicating the starting point for the algorithm (for reproducibility)	0
StreamIndex	Index indicating the associated global stream	1
Substream	Index indicating the associated substream	1

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

Data Types: struct

Tips

• If you have Statistics and Machine Learning Toolbox™, then tallrng controls the random numbers that functions such as datasample, cvpartition, and TreeBagger generate during tall array calculations.

Version History

Introduced in R2017b

R2023b: Specify random number algorithm without specifying seed

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

R2019a: Default random number generator change for tallrng

The default random number generator for tallrng is now threefry. This generator offers performance enhancements for parallel calculations over the old default. In older releases, the default random number generator for tallrng was combRecursive.

With a different default generator, MATLAB will generate different sequences of random numbers by default in the context of tall arrays. However, the statistics of these calculations will remain unaffected. Therefore, you should update any code that relies on the specific random numbers being generated. However, most calculations on the random numbers should be unaffected.

To set the generator to the settings used by default in older releases, use the command:

tallrng(0,"combRecursive")