Managing the Global Stream

rand, randn, and randi draw random numbers from an underlying random number stream, called the global stream. The rng function provides a simple way to control the global stream. For more comprehensive control, the RandStream class allows you to get a handle to the global stream and control random number generation.

Get a handle to the global stream as follows:

globalStream = RandStream.getGlobalStream
globalStream = 

mt19937ar random stream (current global stream)
             Seed: 0
  NormalTransform: Ziggurat

Return the properties of the stream with the get method:

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

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

rand(1,5);

Use the randn and randi functions to generate normal random values and integer random values from the global 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 globalStream.

myState = globalStream.State;

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

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

ans =

     1

rand, randi, and randn access the global 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.

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

ans =

     0

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

stream1=RandStream.getGlobalStream;
stream2=RandStream.getGlobalStream;
stream1.NormalTransform='Polar';
stream2.NormalTransform
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.getGlobalStream`	Get the global random number stream
`RandStream.setGlobalStream`	Set the global 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.
`NormalTransform`	Transformation 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 global stream.

myState=GlobalStream.State;
A=rand(1,100);
GlobalStream.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(GlobalStream)
A=rand(1,100);
reset(GlobalStream)
B=rand(1,100);
isequal(A,B)

ans =

     1

Random Number Data Types

rand and randn generate values in double precision by default.

GlobalStream=RandStream.getGlobalStream;
myState=GlobalStream.State;
A=rand(1,5);
class(A)

ans =

double

To specify the class as double explicitly:

GlobalStream.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.

GlobalStream.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

Documentation

Managing the Global Stream

Random Number Data Types

See Also

Related Topics

MATLAB Documentation

Support