## Documentation Center |

Random number stream

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:

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 The sequence of
random numbers produced by a random number stream |

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

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 |

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

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

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])

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);

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);

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

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);

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);

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'

Was this topic helpful?