**[R] set rngstream** -- Specify the stream for the stream random-number
generator

__Syntax__

**set rngstream** *#*

*#* is any integer between 1 and 32,767.

__Description__

**set** **rngstream** specifies the subsequence, known as a stream, from which
Stata's stream random-number generator should draw random numbers. When
performing a bootstrap estimation or a Monte Carlo simulation in parallel
on multiple machines, you should set the same seed on all machines but
set a different stream on each machine. This will ensure that random
numbers drawn on different machines are independent. We strongly
recommend that you set the seed and the stream only once in each Stata
session.

__Remarks__

Stata's stream random-number generator, the stream 64-bit Mersenne
Twister (**mt64s**), allows separate instances of Stata to simultaneously
draw independent random numbers. This feature enables you to use
**bootstrap** and to run Monte Carlo simulations in parallel on multiple
machines.

What we call random numbers are elements in a sequence of deterministic
numbers that appear to be random. A seed specifies a starting value in
this sequence.

A stream random-number generator partitions a sequence of random numbers
into nonoverlapping subsequences known as streams. The random numbers in
each stream are independent of those in other streams because they come
from distinct nonoverlapping subsets of the original sequence.

In contrast to nonstream random-number generators, setting the seed for a
random-number generator controls not just where the sequence starts but
also how the sequence is partitioned.

The **mt64s** generator is a stream version of Stata's default generator, the
64-bit Mersenne Twister implemented in **mt64**; see Haramoto et al. (2008)
and **set rng** for more details. Our implementation partitions the **mt64**
sequence into 32,767 streams, each containing 2^128 random numbers. The
remaining numbers are unused. The **mt64s** seed determines the starting
point of every stream in the Mersenne Twister sequence.

Stream 1 of **mt64s** has the same starting point as the **mt64** generator.
That is, given the same seed, **mt64s** with **rngstream** set to 1 will generate
the same random numbers as **mt64**.

The **mt64s** generator is designed to simultaneously draw independent random
numbers on different machines. To draw from different streams that
guarantee independence, use the same seed and change the stream. For
example, to draw some uniform(0,1) random numbers from stream 10 of the
**mt64s** generator under seed 123, type

**. set rng mt64s**

**. set rngstream 10**

**. set seed 123**

**. generate u = runiform()**

If we wanted to simultaneously draw some uniform(0,1) random numbers on
another machine from stream 11 of the **mt64s** generator, we would type

**. set rng mt64s**

**. set rngstream 11**

**. set seed 123**

**. generate u = runiform()**

Again, each seed creates a different partition of the **mt64** sequence into
nonoverlapping subsets

We strongly recommend that you set the stream and the seed once in each
Stata session and draw numbers only from this stream.

**c(rngstream)** returns the current stream number. **c(rngseed_mt64s)** returns
the last seed that was set for **mt64s**. See **creturn** for more details. See
**set seed** for details about storing and restoring the current position in
the random sequence.

As with the single-stream generators, use **local state = c(rngstate)** to
store the current position in the current random stream; see **set seed** for
details. The **mt64s** state encodes the seed used in addition to the stream
number, because the seed determines the position of every random number
in every stream. Unlike the case of single-stream generators, restoring
the state also restores the seed. For example, suppose you save an **mt64s**
state with **local state = c(rngstate)** change the seed and the stream, and
later restore that state with **set rngstate `state'**. The current **mt64s**
seed is changed to the one encoded in **state**. In addition to changing the
current stream to the one encoded in **state**, the current **mt64s** seed is
changed to the one encoded in **state**. This behavior ensures any
subsequent stream changes draw from nonoverlapping subsets.

**set rngstream** also sets the random-number generator to **mt64s**.

__Examples__

Perform 100 bootstrap replications on machine 1
**. clear all**
**. webuse auto**
**. set rng mt64s**
**. set rngstream 1**
**. set seed 12345**
**. bootstrap, reps(100) saving(machine1, replace): regress mpg weight**
**gear foreign**

Perform 100 bootstrap replications on machine 2
**. clear all**
**. webuse auto**
**. set rng mt64s**
**. set rngstream 2**
**. set seed 12345**
**. bootstrap, reps(100) saving(machine2, replace): regress mpg weight**
**gear foreign**

After copying **machine2.dta** from machine 2 to the working directory on
machine 1, produce combined results
**. clear all**
**. use machine1**
**. append using machine2**
**. bstat**

__Reference__

Haramoto, H., M. Matsumoto, T. Nishimura, F. Panneton, and P. L'Ecuyer.
2008. Efficient jump ahead for F^2-linear random number generators.
*INFORMS Journal on Computing* 20: 385-390.