RandStream.create

R2026b

Create statistically independent random number streams

Syntax

s = RandStream.create(generator)

[s1,s2,...,sn] = RandStream.create(generator,NumStreams=n)

[___] = RandStream.create(generator,Name=Value)

Description

s = RandStream.create(generator) creates a single random number stream that uses the uniform random number generator algorithm specified by generator. The RandStream function is a more concise alternative when you want to create a single stream.

[s1,s2,...,sn] = RandStream.create(generator,NumStreams=n) creates n random number streams. These streams are mutually independent, but they might not be independent of streams created at other times.

Note

Not all generator algorithms support multiple streams. For more information, see generator. For example, you can use the multiplicative lagged Fibonacci generator ("mlfg6331_64") or the combined multiple recursive generator ("mrg32k3a") to create multiple streams.

[___] = RandStream.create(generator,Name=Value) specifies additional options using one or more name-value arguments.

Examples

Create Streams and Set Global Stream

Create three independent random number streams. Generate random numbers from each stream. Because independent random variables imply zero correlation, check the correlation coefficients among the numbers generated from the three streams. The correlation coefficients between different streams are not exactly 0 because they are calculated from a finite sample of the distribution.

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

R = 3×3

    1.0000    0.0016   -0.0019
    0.0016    1.0000   -0.0012
   -0.0019   -0.0012    1.0000

You can also create one stream from a group of three independent streams

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

Designate the stream as the global stream. Then generate random numbers from the global stream.

RandStream.setGlobalStream(s2)
r2 = rand(100000,1);

Create Independent Streams to Simulate Random Walk

Create three mutually independent streams to simulate one-dimensional random walks. A random walk is a sequence of values obtained by repeatedly adding random increments to the previous value.

[s1,s2,s3] = RandStream.create("mrg32k3a",NumStreams=3);

Generate a random walk from the first stream. First, set it as the global stream. Use the first stream to generate 5000 random steps from the standard normal distribution. Use cumsum to calculate the cumulative sum of the random steps, starting at 0. Plot the resulting random walk.

RandStream.setGlobalStream(s1)
dy1 = randn(5000,1);
y1 = cumsum([0; dy1]);
plot(y1)

Repeat the process using the second and third streams. Plot the results on the same axes.

hold on
dy2 = randn(s2,5000,1);
y2 = cumsum([0; dy2]);
plot(y2)
dy3 = randn(s3,5000,1);
y3 = cumsum([0; dy3]);
plot(y3)
hold off

Calculate the correlation coefficients among the numbers generated from the streams. The correlation coefficients between different streams are not exactly 0 because they are calculated from a finite sample of the distribution.

R = corrcoef([dy1 dy2 dy3])

R = 3×3

    1.0000   -0.0363    0.0155
   -0.0363    1.0000   -0.0012
    0.0155   -0.0012    1.0000

Input Arguments

generator — Random number generator algorithm

"dsfmt19937" | "simdTwister" | "mlfg6331_64" | "multFibonacci" | "mrg32k3a" | "combRecursive" | ...

Random number generator algorithm, specified as a string scalar or character vector containing an algorithm or name from the following table. For example, to create a random number stream using the SIMD-oriented fast Mersenne Twister, you can call s = RandStream.create("dsfmt19937") or s = RandStream.create("simdTwister"). This table describes the available algorithms. Some algorithms support multiple streams and substreams to create sets of random numbers that are mutually independent. For more information, see Create and Control Random Number Streams.

Algorithm	Name	Multiple Stream and Substream Support	Description	Approximate Period in Full Precision
"dsfmt19937"	"simdTwister"	No	SIMD-oriented fast Mersenne Twister	219937 – 1
"mcg16807"	"v4"	No	Multiplicative congruential generator	231 – 2
"mlfg6331_64"	"multFibonacci"	Yes	Multiplicative lagged Fibonacci generator	2124 (251 streams of length 272)
"mrg32k3a"	"combRecursive"	Yes	Combined multiple recursive generator	2191 (263 streams of length 2127)
"mt19937ar"	"twister"	No	Mersenne Twister	219937 – 1
"pcg64dxsm" (since R2026b)	"pcg"	Yes	64-bit permuted congruential generator with double xor-shift multiply	2255 (263 streams of length 2192)
"philox4x32_10"	"philox"	Yes	Philox 4x32 generator with 10 rounds	2193 (264 streams of length 2129)
"shr3cong"	"v5normal"	No	SHR3 shift-register generator summed with linear congruential generator	264
"swb2712"	"v5uniform"	No	Modified subtract-with-borrow generator	21492
"threefry4x64_20"	"threefry"	Yes	Threefry 4x64 generator with 20 rounds	2514 (2256 streams of length 2258)
"xoshiro256pp" (since R2026b)	"xoshiro"	Yes	Xor-shift-rotate generator with 256-bit state and double addition	2256 (264 streams of length 2192)

This argument sets the Type property of the created stream to the specified algorithm.

n — Number of streams

positive integer

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

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: s = RandStream.create("mrg32k3a",NumStreams=3,StreamIndices=2)

Seed — Random number generator seed

0 (default) | nonnegative integer | "shuffle"

Random number generator seed, specified as a nonnegative integer less than 2^32 or "shuffle". The seed specifies the starting point of the algorithm used to generate random numbers. "shuffle" creates a seed based on the current time. If you specify an integer, it must be between 0 and 2³² − 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. Although using multiple seeds creates multiple sequences of random numbers, these sequences are not guaranteed to be statistically independent. To create streams that are statistically independent, use RandStream.create with multiple outputs.

This argument sets the Seed property of the resulting RandStream object.

NumStreams — Number of streams

1 (default) | positive integer

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

This argument sets the NumStreams property of the resulting RandStream object.

StreamIndices — Stream indices

[1:n] (default) | vector of positive integers | positive integer

Stream indices, specified as a vector of positive integers or a positive integer. Specify this name-value argument to index the current stream from among the group of streams with which it was created. The default value is 1:n, where n is the specified value of NumStreams.

This argument sets the StreamIndex property of the resulting RandStream object.

NormalTransform — Normal transformation algorithm

"Ziggurat" | "Polar" | "Inversion"

Normal transformation algorithm to generate normally distributed random numbers using randn, specified as "Ziggurat", "Polar", or "Inversion". For more information, see Create and Control Random Number Streams.

The default normal transformation algorithm depends on the specified generator algorithm:

• "Ziggurat" is the default for dsfmt19937, mlfg6331_64, mrg32k3a, mt19937ar, shr3cong, and swb2712.

• "Polar" is the default for mcg16807.

• "Inversion" is the default for pcg64dxsm, philox4x32_10, threefry4x64_20, and xoshiro256pp.

This argument sets the NormalTransform property of the resulting RandStream object.

Antithetic — Option to generate antithetic random numbers

false or 0 (default) | true or 1

Since R2026b

Option to generate antithetic random numbers, specified as a numeric or logical 0 (false) or 1 (true). When you set Antithetic to true, each uniformly distributed random number u from the original random number stream is transformed to 1-u, producing antithetic variates. This transformation creates negatively correlated sample pairs, which are useful for variance reduction in Monte Carlo simulations.

This argument sets the Antithetic property of the resulting RandStream object.

FullPrecision — Option to use full precision

true or 1 (default) | false or 0

Since R2026b

Option to use full precision when generating random numbers, specified as a numeric or logical 1 (true) or 0 (false). When you set FullPrecision to false, some generators can produce random numbers faster by using fewer bits.

This argument sets the FullPrecision property of the resulting RandStream object.

CellOutput — Option to return cell array

false or 0 (default) | true or 1

Option to return a cell array, specified as a numeric or logical 0 (false) or 1 (true). If you specify CellOutput as true, RandStream.create returns the stream objects as elements of a cell array.

For example, instead of using [s1,s2,s3] = RandStream.create("mrg32k3a",NumStreams=3) to return three separate RandStream objects, you can use S = RandStream.create("mrg32k3a",NumStreams=3,CellOutput=true) to return a 1-by-3 cell array of RandStream objects.

Output Arguments

s — Random number stream

RandStream object | cell array of RandStream objects

Random number stream, returned as a RandStream object or a cell array of RandStream objects.

More About

Random Number Stream

A random number stream is a source for a sequence of pseudorandom numbers generated by a deterministic algorithm. A pseudorandom sequence approximates a theoretical sequence of random numbers whose distribution satisfies the independent and identically distributed (i.i.d.) condition. However, in practice, a deterministic algorithm cannot generate i.i.d. sequences. Instead, the algorithm generates sequences that pass statistical tests of their distribution and correlation, making them suitable approximations for many applications that require random behavior.

Tips

Typically, you call RandStream.create once to create multiple independent streams in a single pass or at the beginning of a MATLAB^® session. For example, you can create three independent streams by using [s1,s2,s3] = RandStream.create("mrg32k3a",NumStreams=3), which returns three separate RandStream objects. As an alternative, you can use S = RandStream.create("mrg32k3a",NumStreams=3,CellOutput=true) to return a 1-by-3 cell array of RandStream objects.

Alternatively, you can create each stream from a separate call to RandStream.create, but you must specify the appropriate values for generator, NumStreams, Seed, and StreamIndices to ensure their independence:

• Specify the same values for generator, NumStreams, and Seed in each case.

• Specify a different value for StreamIndices each time. Specify values between 1 and the value of NumStreams.

For example, create two independent streams by using s1 = RandStream.create("mrg32k3a",NumStreams=5,Seed=0,StreamIndices=1) and s2 = RandStream.create("mrg32k3a",NumStreams=5,Seed=0,StreamIndices=2).

Version History

Introduced in R2008b

R2026b: Specify Antithetic and FullPrecision options

When using RandStream.create to create a RandStream object, you can choose whether to generate antithetic random values or whether to use full precision by specifying the Antithetic or FullPrecision name-value argument, respectively.

R2026b: Generate random numbers using two new algorithms: "pcg" and "xoshiro"

You can use two new algorithms for random number generation.

Name	Algorithm	Multiple Stream and Substream Support	Description	Approximate Period in Full Precision
"pcg"	"pcg64dxsm"	Yes	64-bit permuted congruential generator with double xor-shift multiply	2255 (263 streams of length 2192)
"xoshiro"	"xoshiro256pp"	Yes	Xor-shift-rotate generator with 256-bit state and double addition	2256 (264 streams of length 2192)

Both algorithms also provide the option to use full precision, and they use "Inversion" as the default normal transform.

To select these generator algorithms when controlling the MATLAB random number generator using rng, specify the generator name, such as rng("pcg") or rng("xoshiro"). You can also set either generator as the default by specifying it in the MATLAB Settings Window.

To select these generator algorithms when creating and controlling a random number stream using RandStream or RandStream.create, specify either the generator algorithm or its name, such as RandStream.create("pcg64dxsm") or RandStream.create("pcg").