RandStream

Random number stream

expand all in page

Description

RandStream creates a random number stream using a specified pseudorandom number generator algorithm.

You can generate pseudorandom numbers in MATLAB® from one or more random number streams. The simplest way to generate arrays of random numbers is to use rand, randi, randn, and randperm functions. These functions all rely on the same stream of uniformly distributed random numbers, known as the global stream. Changing the global stream can involve RandStream, but it does not have to. If you create a stream using RandStream, you can use RandStream.setGlobalStream to make it the global stream. However, the rng function provides a simpler interface to create a global stream that is sufficient for most use cases.

You can also use RandStream to create streams and rand, randi, randn, or randperm to generate random numbers separately from those drawn from the global stream of from other streams. For details, see Object Functions.

Creation

Use the following syntaxes to create a single random number stream. If you want to create multiple independent streams simultaneously, use the RandStream.create function.

Syntax

s = RandStream(gentype)
s = RandStream(gentype,Name,Value)

Description

example

s = RandStream(gentype) creates a random number stream that uses the uniform pseudorandom number generator algorithm specified by gentype.

example

s = RandStream(gentype,Name,Value) also controls properties of the stream using one or more optional Name,Value pair arguments.

Input Arguments

expand all

Random number generator algorithm, specified as a character vector or string scalar naming a random number generator. MATLAB offers several generator algorithms. The following table summarizes the names and key properties of the available generator algorithms. Some generator algorithms support multiple streams and substreams to create sets of random numbers that are mutually independent. For more information, see Choosing a Random Number Generator.

NameGeneratorMultiple Stream and Substream SupportApproximate Period In Full Precision
'mt19937ar'Mersenne Twister (used by default stream at MATLAB startup)No219937-1
'dsfmt19937'SIMD-Oriented Fast Mersenne Twister No219937-1
'mlfg6331_64'Multiplicative lagged Fibonacci generatorYes2124 (251 streams of length 272)
'mrg32k3a'Combined multiple recursive generatorYes2191 (263 streams of length 2127)
'philox4x32_10'Philox 4x32 generator with 10 roundsYes2193 (264 streams of length 2129)
'threefry4x64_20'Threefry 4x64 generator with 20 roundsYes2514 (2256 streams of length 2258)
'shr3cong'Shift-register generator summed with linear congruential generatorNo264
'swb2712'Modified subtract with borrow generatorNo21492
'mcg16807'Multiplicative congruential generatorNo231-2
Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: s = RandStream('mt19937ar','Seed',15,'NormalTransform','Polar')

Random number seed, specified as the comma-separated pair consisting of 'Seed' and a nonnegative integer or 'shuffle'. The seed specifies the starting point for the algorithm to generate random numbers. 'shuffle' creates a seed based on the current time. If you specify an integer, it must be between 0 and 232 − 1.

Specify the generator seed as an initialization step when creating a stream at MATLAB startup or before running a simulation. To reproduce a stream, use the same seed every time. While using multiple seeds will create multiple sequences of random numbers, there is no guarantee that the different sequences are statistically independent. In situations where this is important, specify the Substream property or use RandStream.create to create streams that are statistically independent.

Transformation algorithm to generate normally distributed random numbers from the random number stream using randn, specified as the comma-separated pair consisting of 'NormalTransform' and one of the algorithm names 'Ziggurat','Polar', or 'Inversion'. For more information, see Creating and Controlling a Random Number Stream.

Properties

expand all

A random number stream s has properties that control its behavior. Access a property using p = s.Property and modify one using s.Property = p. To save and restore all properties of a stream s, you can use A = get(s) and set(s,A), respectively. The following list provides the properties of RandStream.

This property is read-only.

Random number generator algorithm used by the stream. See the table of generator algorithms for a summary of generators and their properties.

Not all generators algorithms support multiple streams. For some generators, you can create multiple streams and substreams that are statistically independent.

Data Types: char

This property is read-only.

Random number seed used to create the stream, returned as a nonnegative integer.

Data Types: uint32

This property is read-only.

Number of streams in the group in which the current stream was created, returned as a positive integer.

Data Types: uint64

This property is read-only.

Index of the current stream from among the group of streams with which it was created, returned as a positive integer.

Data Types: uint64

Current internal state of the generator, specified as a vector of integers. The size of the state vector depends on the generator algorithm. When you set 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 its initial state without having previously read from the State property. Saving and restoring the internal state of the generator with the State property allows you to reproduce a sequence of random numbers.

The internal state determines the sequence of random numbers produced by the random number stream s. Every time you generate random numbers from a single stream, the state of the generator in the stream is transformed to create successive values that are statistically independent and identically distributed.

Note

Only restore the state of a random number stream, or reset a stream, to reproduce results from the stream.

Data Types: uint32

Index of the substream to which the stream is currently set.

For some generator types, you can create different substreams from a random stream. Values generated from different substreams are mutually independent. See the table of generator algorithms for generators that support substreams.

Data Types: double

Transformation algorithm to generate normally distributed pseudorandom values using randn.

Data Types: char

Whether s generates antithetic pseudorandom values, specified as logical true (1) or false (0). Antithetic values are the default generated pseudorandom values with uniform distribution subtracted from 1.

Data Types: logical

Whether s generates values using its full precision, specified as logical true (1) or false (0). Some generators can create pseudorandom values faster, but with fewer random bits, if FullPrecision is false.

Data Types: logical

Object Functions

By default, random number generation functions, such as rand, use the global random number stream. To specify a different stream, create a RandStream object and pass it as the first input argument. For instance, create a 4-by-1 vector of random numbers using the SIMD-oriented fast Mersenne twister.

s = RandStream('dsfmt19937');
r = rand(s,4,1);

These functions accept a RandStream object:

randUniformly distributed random numbers

Supported syntaxes, where s is a RandStream object:

X = rand(s)
X = rand(s,n)
X = rand(s,sz1,...,szN)
X = rand(s,sz)
X = rand(s,typename)
For details on other input arguments, see rand, randi, and randn.

randiUniformly distributed pseudorandom integers
randnNormally distributed random numbers
randpermRandom permutation of integers

Supported syntaxes, where s is a RandStream object:

p = randperm(s,n)
p = randperm(s,n,k)
For details on other input arguments, see randperm.

Other object functions of RandStream are:

RandStream.createCreate statistically independent random number streams
RandStream.listList random number generator algorithms
RandStream.getGlobalStreamGet current global random number stream
RandStream.setGlobalStreamSet global random number stream
resetReset random number stream

Examples

collapse all

Open Live Script

Create a random number stream using the SIMD-Oriented Fast Mersenne Twister.

s = RandStream('dsfmt19937')
s = 
dsfmt19937 random stream
             Seed: 0
  NormalTransform: Ziggurat

Use the stream to generate five random numbers.

rand(s,1,5)
ans = 1×5

    0.0306    0.2131    0.2990    0.3811    0.8635
Open Live Script

Create a random number stream using a generator seed based on the current time. 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');

Use the stream to create a 3-by-3 matrix of random values with uniform distribution between 0 and 1.

X1 = rand(s,3)
X1 = 3×3

    0.0359    0.1928    0.5177
    0.0030    0.1561    0.4449
    0.7540    0.9466    0.7731

Create another five random numbers from the stream.

X2 = rand(s,1,5)
X2 = 1×5

    0.9629    0.0221    0.8222    0.9187    0.6404
Open Live Script

Create a random number stream whose seed is zero.

s = RandStream('mcg16807','Seed',0);

Generate five random numbers from the stream. Every time you generate a number from the stream, the generator algorithm transforms the internal state such that the next generated number is independent and identically distributed from the previous number.

u1 = rand(s,1,5)
u1 = 1×5

    0.2190    0.0470    0.6789    0.6793    0.9347

Save the current state of the generator. Generate another five random numbers.

savedState = s.State;
u2 = rand(s,1,5)
u2 = 1×5

    0.3835    0.5194    0.8310    0.0346    0.0535

To reproduce the last outcome of five random numbers, restore the generator state to the saved state.

s.State = savedState;
u3 = rand(s,1,5)
u3 = 1×5

    0.3835    0.5194    0.8310    0.0346    0.0535

Only read and write the generator state to reproduce a specific outcome from the stream.

Open Live Script

Create a random number stream whose seed is three. Use the stream to generate eight random numbers.

stream = RandStream('dsfmt19937','Seed',3);
z = rand(stream,1,8)
z = 1×8

    0.2550    0.8753    0.0908    0.1143    0.3617    0.8210    0.8444    0.6189

Reset the random number stream to its initial state with seed equal to three. Reproduce the eight random numbers that were generated.

reset(stream,3);
z = rand(stream,1,8)
z = 1×8

    0.2550    0.8753    0.0908    0.1143    0.3617    0.8210    0.8444    0.6189

Resetting a stream's seed can invalidate independence with other streams. Only reset a stream to reproduce results from the stream.

Open Live Script

Create two random number streams. Set the first stream as a global stream by using RandStream.setGlobalStream.

globalStream = RandStream('mlfg6331_64','NormalTransform','Polar')
globalStream = 
mlfg6331_64 random stream
             Seed: 0
  NormalTransform: Polar

RandStream.setGlobalStream(globalStream);

To show the current global stream, use RandStream.getGlobalStream.

RandStream.getGlobalStream
ans = 
mlfg6331_64 random stream (current global stream)
             Seed: 0
  NormalTransform: Polar

Create a second stream myStream that acts separately from the new global stream that you created.

myStream = RandStream('dsfmt19937','NormalTransform','Inversion')
myStream = 
dsfmt19937 random stream
             Seed: 0
  NormalTransform: Inversion

Generate three random numbers from the global stream. Generate another three random numbers from the local stream myStream that you created.

randn(1,3)
ans = 1×3

    0.8715    1.0588   -0.6956


randn(myStream,1,3)
ans = 1×3

   -1.8723   -0.7956   -0.5273

When you call the functions rand, randn, and randi without myStream, they draw from the global stream, and will not affect the results of calling them with myStream.

Open Live Script

For some generator types, you can create different substreams from a random stream. Values generated from different substreams are mutually independent.

For instance, create a random number stream using a combined multiple recursive generator.

s = RandStream('mrg32k3a');

To reposition a stream to a particular substream, set its Substream property. For instance, generate random numbers in a loop. Position the random number stream to the beginning of a different substream before each iteration of the loop. Generate 3 mutually independent sets of 5 random numbers.

for i = 1:3
    s.Substream = i;
    z = rand(s,1,5)
end
z = 1×5

    0.7270    0.4522    0.9387    0.2360    0.0277


z = 1×5

    0.5582    0.8527    0.7733    0.0633    0.2788


z = 1×5

    0.1666    0.2924    0.7728    0.8391    0.5107

To reproduce the second set of 5 random numbers, reposition the stream to the corresponding substream.

s.Substream = 2;
z = rand(s,1,5)
z = 1×5

    0.5582    0.8527    0.7733    0.0633    0.2788

More About

expand all

See Also

| | | |

Topics

Introduced in R2008b

MATLAB Documentation

Support