Documentation Center

  • Trials
  • Product Updates

RandStream

Random number stream

Constructor

RandStream

Description

Pseudorandom numbers in MATLAB® come from one or more random number streams. The simplest way to generate arrays of random numbers is to use rand, randn, or randi. These functions all rely on the same stream of uniform random numbers, known as the global stream. You can create other streams that act separately from the global stream, and you can use their rand, randi, or randn methods to generate arrays of random numbers. You can also create a random number stream and make it the global stream.

To create a single random number stream, use the RandStream constructor. To create multiple independent random number streams, use RandStream.create. The rng function provides a simple interface to create a new global stream.

stream = RandStream.getGlobalStream returns the global random number stream, that is, the one currently used by the rand, randi, and randn functions.

prevstream = RandStream.setGlobalStream(stream) designates the random number stream stream as the new global stream to be used by the rand, randi, and randn functions, and returns the previous global stream.

A random number stream s has properties that control its behavior. Access or assign to a property using p = s.Property or s.Property = p. The following table lists defined properties:

Properties

PropertyDescription
Type(Read-only) Generator algorithm used by the stream. The list of possible generators is given by RandStream.list.
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 it was created.
State

Internal state of the generator. You should not depend on the format of this property. The value you assign to S.State must be a value read from S.State previously. Use reset to return a stream to a predictable state without having previously read from the State property.

The sequence of random numbers produced by a random number stream s is determined by the internal state of its random number generator. Saving and restoring the generator's internal state with the State property allows you to reproduce a sequence of random numbers.

SubstreamIndex 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.
NormalTransformTransformation algorithm used by randn(s, ...) to generate normal pseudorandom values. Possible values are 'Ziggurat', 'Polar', or 'Inversion'.
AntitheticLogical value indicating whether S generates antithetic pseudorandom values, that is, the usual values subtracted from 1. The default is false.
FullPrecisionLogical 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.

Methods

MethodDescription
RandStreamCreate a random number stream.
RandStream.createCreate multiple independent random number streams.
getGet the properties of a random stream object.
listList available random number generator algorithms.
setSet random stream property.
RandStream.getGlobalStreamGet the global random number stream.
RandStream.setGlobalStreamSet global random number stream.
resetReset a stream to its initial internal state
randPseudorandom numbers from a uniform distribution
randnPseudorandom numbers from a standard normal distribution
randiPseudorandom integers from a uniform discrete distribution
randpermRandom permutation of a set of values

Examples

Example 1

Create a single stream and designate it as the current global stream:

s = RandStream('mt19937ar','Seed',1);
RandStream.setGlobalStream(s);

Example 2

Create three independent streams:

[s1,s2,s3] = RandStream.create('mrg32k3a','NumStreams',3);
r1 = rand(s1,100000,1);
r2 = rand(s2,100000,1);
r3 = rand(s3,100000,1);
corrcoef([r1,r2,r3])

Example 3

Create only one stream from a set of three independent streams, and designate it as the current global stream:

s2 = RandStream.create('mrg32k3a','NumStreams',3,...
     'StreamIndices',2);
RandStream.setGlobalStream(s2);

Example 4

Reset the global random number stream that underlies rand, randi, and randn back to its beginning, to reproduce previous results:

stream = RandStream.getGlobalStream;
reset(stream);

Example 5

Save and restore the current global stream's state to reproduce the output of rand:

stream = RandStream.getGlobalStream;
savedState = stream.State;
u1 = rand(1,5)
u1 =
    0.8147    0.9058    0.1270    0.9134    0.6324

stream.State = savedState;
u2 = rand(1,5)
u2 =
    0.8147    0.9058    0.1270    0.9134    0.6324

u2 contains exactly the same values as u1.

Example 6

Reset the global random number stream to its initial settings. This causes rand, randi, and randn to start over, as if in a new MATLAB session:

s = RandStream('mt19937ar','Seed',0);
RandStream.setGlobalStream(s);

Example 7

Reinitialize the global random number stream using a seed based on the current time. This causes rand, randi, and randn to return different values in different MATLAB sessions. It is usually not desirable to do this more than once per MATLAB session as it may affect the statistical properties of the random numbers MATLAB produces:

s = RandStream('mt19937ar','Seed','shuffle');
RandStream.setGlobalStream(s);

Example 8

Change the transformation algorithm that randn uses to create normal pseudorandom values from uniform values. This does not replace or reset the global stream.

stream = RandStream.getGlobalStream;
stream.NormalTransform = 'inversion'

See Also

| | |

Was this topic helpful?