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

Property	Description
`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.
`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, that is, 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.

Methods

Method	Description
`RandStream`	Create a random number stream.
`RandStream.create`	Create multiple independent random number streams.
`get`	Get the properties of a random stream object.
`list`	List available random number generator algorithms.
`set`	Set random stream property.
`RandStream.getGlobalStream`	Get the global random number stream.
`RandStream.setGlobalStream`	Set global random number stream.
`reset`	Reset a stream to its initial internal state
`rand`	Pseudorandom numbers from a uniform distribution
`randn`	Pseudorandom numbers from a standard normal distribution
`randi`	Pseudorandom integers from a uniform discrete distribution
`randperm`	Random 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'

Documentation