Learn more about MATLAB

Managing the Default Stream

On this page…
Random Number Data Types

rand, randn, and randi draw random numbers from an underlying random number stream, called the default stream. The @RandStream class allows you to get a handle to the default stream and control random number generation.

Get a handle to the default stream as follows:

defaultStream=RandStream.getDefaultStream

defaultStream = 

mt19937ar random stream (current default)
             Seed: 0
         RandnAlg: Ziggurat

Return the properties of the stream object with the get method:

get(defaultStream)
             Type: 'mt19937ar'
       NumStreams: 1
      StreamIndex: 1
        Substream: 1
             Seed: 0
            State: [625x1 uint32]
         RandnAlg: 'Ziggurat'
       Antithetic: 0
    FullPrecision: 1

Now, use the rand function to generate uniform random values from the default stream.

rand(1,5);

Use the randn and randi functions to generate normal random values and integer random values from the default stream.

A=randi(100,1,5);
A=randn(1,5);

The State property is the internal state of the generator. You can save the State of defaultStream.

myState=defaultStream.State;

Using myState, you can restore the state of defaultStream and reproduce previous results.

myState=defaultStream.State;
A=rand(1,100);
defaultStream.State=myState;
B=rand(1,100);
isequal(A,B)

ans =

     1

rand, randi, and randn access the default stream. Since all of these functions access the same underlying stream, a call to one affects the values produced by the others at subsequent calls.

defaultStream.State=myState;
A=rand(1,100);
defaultStream.State=myState;
randi(100);
B=rand(1,100);
isequal(A,B)

ans =

     0

The default stream is a handle object of the @RandStream class. RandStream.getDefaultStream returns a handle. The properties of the default stream can be viewed or modified from any handle to the stream.

stream1=RandStream.getDefaultStream;
stream2=RandStream.getDefaultStream;
stream1.RandnAlg='Polar';
stream2.RandnAlg
ans =

Polar

The following table shows the methods available for the @RandStream class. Static methods are indicated with the syntax RandStream.methodName.

Method	Description
RandStream	Create a random number stream
RandStream.create	Create multiple independent random number streams
get	Get the properties of a random stream
RandStream.list	List available random number generator algorithms
RandStream.getDefaultStream	Get the default random number stream
RandStream.setDefaultStream	Set the default random number stream
set	Set a property of a random stream
reset	Reset a stream to its initial internal state
rand	Generate pseudorandom numbers from a uniform distribution
randn	Generate pseudorandom numbers from a standard normal distribution
randi	Generate pseudorandom integers from a uniform discrete distribution
randperm	Random permutation of a set of values

The properties of a random stream are given the following table.

Property	Description
Type	(Read-only) Generator algorithm used by the stream. RandStream.list specifies the possible generators.
Seed	(Read-only) Seed value used to create the stream.
NumStreams	(Read-only) Number of streams in the group in which the current stream was created.
StreamIndex	(Read-only) Index of the current stream from among the group of streams with which the current stream was created.
State	Internal state of the generator. Do not depend on the format of this property. The value you assign to S.State must be a value previously read from S.State.
Substream	Index of the substream to which the stream is currently set. The default is 1. Multiple substreams are not supported by all generator types; the multiplicative lagged Fibonacci generator (mlfg6331_64) and combined multiple recursive generator (mrg32k3a) support substreams.
RandnAlg	Algorithm used by randn(s, ...) to generate normal pseudorandom values. Possible values are 'Ziggurat', 'Polar', or 'Inversion'.
Antithetic	Logical value indicating whether S generates antithetic pseudorandom values. For uniform values, these are the usual values subtracted from 1. The default is false.
FullPrecision	Logical value indicating whether s generates values using its full precision. Some generators can create pseudorandom values faster, but with fewer random bits, if FullPrecision is false. The default is true.

Suppose you want to repeat a simulation. The @RandStream class gives you several ways to replicate output. As shown in the previous example, you can save the state of the default stream.

myState=defaultStream.State;
A=rand(1,100);
defaultStream.State=myState;
B=rand(1,100);
isequal(A,B)

ans =

     1

You can also reset a stream to its initial settings with the method reset.

reset(defaultStream)
A=rand(1,100);
reset(defaultStream)
B=rand(1,100);
isequal(A,B)

ans =

     1

Random Number Data Types

rand and randn generate values in double precision by default.

defaultStream=RandStream.getDefaultStream;
myState=defaultStream.State;
A=rand(1,5);
class(A)

ans =

double

To specify the class as double explicitly:

defaultStream.State=myState;
B=rand(1,5,'double');
class(B)

ans =

double
isequal(A,B)

ans =

     1

rand and randn will also generate values in single precision.

defaultStream.State=myState;
A=rand(1,5,'single');
class(A)
ans =

single

The values are the same as if you had cast the double precision values from the previous example. The random stream that the functions draw from advances the same way regardless of what class of values is returned.

A,B

A =

    0.8235    0.6948    0.3171    0.9502    0.0344


B =

    0.8235    0.6948    0.3171    0.9502    0.0344

randi supports both integer types and single or double precision.

A=randi([1 10],1,5,'double');
class(A)

ans =

double
B=randi([1 10],1,5,'uint8');
class(B)

ans =

uint8

Back to Top

Generating Random Numbers

Creating and Controlling a Random Number Stream

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS