Documentation

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

MethodDescription
`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.

PropertyDescription
`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```