Learn more about MATLAB

Creating and Controlling a Random Number Stream

The @RandStream class allows you to create a random number stream. This is useful for several reasons. For example, you might want to generate random values without affecting the state of the default stream. You might want separate sources of randomness in a simulation. Or you may need to use a different generator algorithm than the one MATLAB software uses at startup. With the RandStream constructor, you can create your own stream, set the writable properties, and use it to generate random numbers. You can control the stream you create the same way you control the default stream. You can even replace the default stream with the stream you create.

To create a stream, use the RandStream constructor.

myStream=RandStream('mlfg6331_64');
rand(myStream,1,5)

ans =

    0.6530    0.8147    0.7167    0.8615    0.0764

The random stream myStream acts separately from the default stream. The functions rand, randn, and randi will continue to draw from the default stream, and will not affect the results of the @RandStream methods rand, randn and randi applied to myStream.

You can make myStream the default stream using the RandStream.setDefaultStream method.

RandStream.setDefaultStream(myStream)
RandStream.getDefaultStream

ans = 

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

RandStream.getDefaultStream==myStream

ans =

     1

Substreams

You may want to return to a previous part of a simulation. A random stream can be controlled by having it jump to fixed checkpoints, called substreams. The Substream property allows you to jump back and forth among multiple substreams. To use the Substream property, create a stream using a generator that supports substreams. (See Choosing a Random Number Generator for a list of generator algorithms and their properties.)

stream=RandStream('mlfg6331_64');
RandStream.setDefaultStream(stream)

The initial value of Substream is 1.

stream.Substream

ans =

     1

Substreams are useful in serial computation. Substreams can recreate all or part of a simulation by returning to a particular checkpoint in stream. For example, they can be used in loops.

for i=1:5
    stream.Substream=i;
    rand(1,i)
end

ans =
    0.6530

ans =
    0.3364    0.8265

ans =
    0.9539    0.6446    0.4913

ans =
    0.0244    0.5134    0.6305    0.6534

ans =
    0.3323    0.9296    0.5767    0.1233    0.6934

Each of these substreams can reproduce its loop iteration. For example, you can return to the 5th substream. The result will return the same values as the 5th output above.

stream.Substream=5;
rand(1,5)

ans =

    0.3323    0.9296    0.5767    0.1233    0.6934

Back to Top

Choosing a Random Number Generator

MATLAB software offers six generator algorithms. The following table summarizes the key properties of the available generator algorithms and the keywords used to create them. To return a list of all the available generator algorithms, use the RandStream.list method.

Generator algorithms

Keyword	Generator	Multiple Stream and Substream Support	Approximate Period In Full Precision
mt19937ar	Mersenne twister (default)	No
mcg16807	Multiplicative congruential generator	No
mlfg6331_64	Multiplicative lagged Fibonacci generator	Yes
mrg32k3a	Combined multiple recursive generator	Yes
shr3cong	Shift-register generator summed with linear congruential generator	No
swb2712	Modified subtract with borrow generator	No

Some of the generators (mt16807, shr3, swb2712) provide for backwards compatibility with earlier versions of MATLAB. Two generators (mrg32k3a, mlfg6331_64) provide explicit support for parallel random number generation. The remaining generator (mt19937ar) is designed primarily for sequential applications. Depending on the application, some generators may be faster or return values with more precision.

Another reason for the choice of generators has to do with applications. All pseudorandom number generators are based on deterministic algorithms, and all will fail a sufficiently specific statistical test for randomness. One way to check the results of a Monte Carlo simulation is to rerun the simulation with two or more different generator algorithms, and MATLAB software's choice of generators provide you with the means to do that. Although it is unlikely that your results will differ by more than Monte Carlo sampling error when using different generators, there are examples in the literature where this kind of validation has turned up flaws in a particular generator algorithm (see [10] for an example).

Generator Algorithms

mcg16807

A 32-bit multiplicative congruential generator, as described in [11], with multiplier , modulo . This generator has a period of and does not support multiple streams or substreams. Each U(0,1) value is created using a single 32-bit integer from the generator; the possible values are all multiples of strictly within the interval (0,1). The randn algorithm used by default for mcg16807 streams is the polar algorithm (described in [1]). Note: This generator is identical to the one used beginning in MATLAB Version 4 by both the rand and randn functions, activated using rand('seed',s) or randn('seed',s).

mlfg6331_64

A 64-bit multiplicative lagged Fibonacci generator, as described in [8], with lags , . This generator is similar to the MLFG implemented in the SPRNG package. It has a period of approximately . It supports up to parallel streams, via parameterization, and substreams each of length . Each U(0,1) value is created using one 64-bit integer from the generator; the possible values are all multiples of strictly within the interval (0,1). The randn algorithm used by default for mlfg6331_64 streams is the ziggurat algorithm [5], but with the mlfg6331_64 generator underneath.

mrg32k3a

A 32-bit combined multiple recursive generator, as described in [3]. This generator is similar to the CMRG implemented in the RngStreams package. It has a period of , and supports up to parallel streams, via sequence splitting, and substreams each of length . Each U(0,1) value is created using two 32-bit integers from the generator; the possible values are multiples of strictly within the interval (0,1). The randn algorithm used by default for mrg32k3a streams is the ziggurat algorithm [5], but with the mrg32k3a generator underneath.

mt19937ar

The Mersenne Twister, as described in [9], with Mersenne prime . This is the generator documented at http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html. It has a period of . Each U(0,1) value is created using two 32-bit integers from the generator; the possible values are all multiples of strictly within the interval (0,1). This generator does not support multiple streams or substreams. The randn algorithm used by default for mt19937ar streams is the ziggurat algorithm [5], but with the mt19937ar generator underneath. Note: This generator is identical to the one used by the rand function beginning in MATLAB Version 7, activated using rand('twister',s).

shr3cong

Marsaglia's SHR3 shift-register generator summed with a linear congruential generator with multiplier , addend , and modulus . SHR3 is a 3-shift-register generator defined as , where is the identity operator, is the left shift operator, and R is the right shift operator. The combined generator (described in [4]) has a period of approximately . This generator does not support multiple streams or substreams. Each U(0,1) value is created using one 32-bit integer from the generator; the possible values are all multiples of strictly within the interval (0,1). The randn algorithm used by default for shr3cong streams is the earlier form of the ziggurat algorithm [7], but with the shr3cong generator underneath. Note: This generator is identical to the one used by the randn function beginning in MATLAB Version 5, activated using randn('state',s).

swb2712

A modified Subtract-with-Borrow generator, as described in [6]. This generator is similar to an additive lagged Fibonacci generator with lags 27 and 12, but is modified to have a much longer period of approximately . The generator works natively in double precision to create U(0,1) values, and all values in the open interval (0,1) are possible. The randn algorithm used by default for swb2712 streams is the ziggurat algorithm [5], but with the swb2712 generator underneath. Note: This generator is identical to the one used by the rand function beginning in MATLAB Version 5, activated using rand('state',s).

Transformation Algorithms

Inversion

Computes a normal random variate by applying the standard normal inverse cumulative distribution function to a uniform random variate. Exactly one uniform value is consumed per normal value.

Polar

The polar rejection algorithm, as described in [1]. Approximately 1.27 uniform values are consumed per normal value, on average.

Ziggurat

The ziggurat algorithm, as described in [5]. Approximately 2.02 uniform values are consumed per normal value, on average.

Back to Top

Compatibility Considerations

In MATLAB versions 7.6 and prior, the way to replicate results involving random numbers was to use keyword and seed value arguments with the rand and randn functions.

rand('twister',5489)
rand

ans =

    0.8147

rand('twister',5489)
rand

ans =

    0.8147

or to control the output by saving and restoring the state of the generator:

oldstate=rand('twister');
rand
ans =

    0.8147

rand('twister',oldstate)
rand

ans =

    0.8147

Using a @RandStream stream object simplifies this procedure. In the previous example, you need to know that you are using the generator for 'twister' in order to restore the saved state oldstate. With the @RandStream syntax, you can check what type of generator is active using the Type property. You can even reproduce results without knowing what type of generator is active or what properties are set. All that is necessary is to get a handle to the default stream with RandStream.getDefaultStream.

savedStream=RandStream.getDefaultStream;
savedState=savedStream.State;
A=rand(100);
savedStream.State=savedState;
B=rand(100);
isequal(A,B)
ans =

     1

See the section Legacy Mode for more information on compatibility issues.

Back to Top

Managing the Default Stream

Multiple streams

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