Replace Discouraged Syntaxes of rand and randn

Description of the Discouraged Syntaxes

In earlier versions of MATLAB^®, you controlled the random number generator used by the rand and randn functions with the 'seed', 'state' or 'twister' inputs. For example:

rand('seed',sd)
randn('seed',sd)
rand('state',s)
randn('state',s)
rand('twister',5489)

These syntaxes referred to different types of generators, and they are no longer recommended for the following reasons:

The terms 'seed' and 'state' are misleading names for the generators.
All of the generators except 'twister' are flawed.
They unnecessarily use different generators for rand and randn.

To assess the impact of replacing discouraged syntaxes in your existing code, execute the following commands at the start of your MATLAB session:

warning('on','MATLAB:RandStream:ActivatingLegacyGenerators')
warning('on','MATLAB:RandStream:ReadingInactiveLegacyGeneratorState')

Description of Replacement Syntaxes

Use the rng function to control the shared generator used by rand, randn, randi and all other random number generation functions like randperm, sprand, and so on. To learn how to use the rng function when replacing discouraged syntaxes, take a few moments to understand their function. This should help you to see which new rng syntax best suits your needs.

The first input to rand(Generator,s) or randn(Generator,s) specified the type of the generator, as described here.

Generator = 'seed' referred to the MATLAB v4 generator, not to the seed initialization value.

Generator = 'state' referred to the MATLAB v5 generators, not to the internal state of the generator.

Generator = 'twister' referred to the Mersenne Twister generator, now the MATLAB startup generator.

The v4 and v5 generators are no longer recommended unless you are trying to exactly reproduce the random numbers generated in earlier versions of MATLAB. The simplest way to update your code is to use rng. The rng function replaces the names for the rand and randn generators as follows.

rand/randn Generator Name	rng Generator Name
`'seed'`	`'v4'`
`'state'`	`'v5uniform'` (for `rand`) or `'v5normal'` (for `randn`)
`'twister'`	`'twister'` (recommended)

Replacement Syntaxes for Initializing the Generator with an Integer Seed

The most common uses of the integer seed sd in the rand(Generator,sd) syntax were to:

Reproduce exactly the same random numbers each time (e.g., by using a seed such as 0, 1, or 3141879)
Try to ensure that MATLAB always gives different random numbers in separate runs (for example, by using a seed such as sum(100*clock))

The following table shows replacements for syntaxes with an integer seed sd.

The first column shows the discouraged syntax with rand and randn.
The second column shows how to exactly reproduce the discouraged behavior with the new rng function. In most cases, this is done by specifying a legacy generator type such as the v4 or v5 generators, which is no longer recommended.
The third column shows the recommended alternative, which does not specify the optional generator type input to rng. Therefore, if you always omit the Generator input, rand, randn, and randi just use the default generator type and seed value. The default generator type used at MATLAB startup is the Mersenne Twister generator with seed value of 0. You can change the default algorithm and seed for the random number generator in MATLAB preferences (since R2023b). For more details, see rng.

Discouraged rand/randn Syntax	Not Recommended: Reproduce Discouraged Behavior Exactly By Specifying Generator Type	Recommended Alternative: Does Not Override Generator Type
`rand('twister',5489)`	`rng(5489,'twister')`	`rng('default')`
`rand('seed',sd)`	`rng(sd,'v4')`	`rng(sd)`
`randn('seed',sd)`	`rng(sd,'v4')`
`rand('state',sd)`	`rng(sd,'v5uniform')`
`randn('state',sd)`	`rng(sd,'v5normal')`
`rand('seed',sum(100*clock))`	`rng(sum(100*clock),'v4')`	`rng('shuffle')`

Replacement Syntaxes for Initializing the Generator with a State Vector

The most common use of the state vector (shown here as st) in the rand(Generator,st) syntax was to reproduce exactly the random numbers generated at a specific point in an algorithm or iteration. For example, you could use this vector as an aid in debugging.

The rng function changes the pattern of saving and restoring the state of the random number generator as shown in the next table. The example in the left column assumes that you are using the v5 uniform generator. The example in the right column uses the new syntax, and works for any generator you use.

Discouraged Syntax Using rand/randn	New Syntax Using rng
% Save v5 generator state. st = rand('state'); % Call rand. x = rand; % Restore v5 generator state. rand('state',st); % Call rand again and hope % for the same results. y = rand	% Get generator settings. s = rng; % Call rand. x = rand; % Restore previous generator % settings. rng(s); % Call rand again and % get the same results. y = rand

Discouraged Syntax Using rand/randn

New Syntax Using rng

% Save v5 generator state.
st = rand('state');

% Call rand.
x = rand;

% Restore v5 generator state.
rand('state',st);

% Call rand again and hope 
% for the same results.
y = rand

% Get generator settings.
s = rng;

% Call rand.
x = rand;

% Restore previous generator 
% settings.
rng(s);

% Call rand again and 
% get the same results.
y = rand

For a demonstration, see this instructional video.

If You Are Unable to Upgrade from Discouraged Syntax

If there is code that you are not able or not permitted to modify and you know that it uses the discouraged random number generator control syntaxes, it is important to remember that when you use that code MATLAB will switch into legacy mode. In legacy mode, rand and randn are controlled by separate generators, each with their own settings.

Calls to rand in legacy mode use one of the following:

The 'v4' generator, controlled by rand('seed', ...)
The 'v5uniform' generator, controlled by rand('state', ...)
The 'twister' generator, controlled by rand('twister', ...)

Calls to randn in legacy mode use one of the following:

The 'v4' generator, controlled by randn('seed', ...)
The 'v5normal' generator, controlled by randn('state', ...)

If code that you rely on puts MATLAB into legacy mode, use the following command to escape legacy mode and get back to the default startup generator:

rng('default')

Alternatively, to guard around code that puts MATLAB into legacy mode, use:

s = rng     % Save current settings of the generator.
  ...       % Call code using legacy random number generator syntaxes.
rng(s)      % Restore previous settings of the generator.