Controling Random Number Generator

DESCRIPTION:

Set and inspect the state of the random number generator.

USAGE:

RNGkind(kind = NULL, normal.kind = NULL)
set.seed(i, congruential, tausworthe) 
.Random.seed

OPTIONAL ARGUMENTS:

kind
If a string, it must be one of "default", "Super-Duper", "Mersenne-Twister", or "user-supplied" or an unambiguous abbreviation of one of those and it specifies the name of the desired random uniform generator. Currently "default" is equivalent to "Super-Duper", but that may change in the future. If kind is NULL, the default value, then RNGkind returns the name of the current random uniform generator and does not change it. See below for more information on the available random uniform generators.
normal.kind
This argument is ignored by the random number generating system and a warning is given if you use it. It is here so the R code using it will not break.
i
an integer scalar, or a previous value of .Random.seed used to set the state of the random uniform generator. Each random uniform generator interprets the integer scalar in its own way. E.g., "Super-Duper" only looks at i%%1024 but "Mersenne-Twister" uses all of it. "Super-Duper" has 2 extra seed arguments to partially make up for that deficiency.
congruential
an integer used only by the "Super-Duper" random uniform generator. The number of steps to iterate the congruential part of the "Super-Duper" generator from its default starting point. This iterating is done by a call to a power function, so it is quick for any value of the argument.
tausworthe
an integer used only by the "Super-Duper" random uniform generator. The number of steps to iterate the Tausworthe part of the "Super-Duper" generator. Each iteration involves two shifts and xor operations per cycle so can take a while for very large numbers of iterations (there is no analogue to a power function for iterating this).



For the "Super-Duper" generator, if i is an integer between 0 and 1023 then set.seed(i) is equivalent to set.seed(cong=i*2^20,taus=0). Each time a random uniform is generated both the congruential and Tausworthe parts of the seed are updated, so if you use identical values of congruential and tausworthe you will be sampling in the same stream of random numbers as you would when both are 0.

For the "Super-Duper" generator, the various streams started by set.seed(i) for i 0:1023 can have uncomfortable amounts of dependency and you will get more independent streams by calling set.seed(i) followed by set.seed(tausworthe=i*7). The "Mersenne-Twister" generator does not have this problem.

SIDE EFFECTS:

set.seed and RNGkind both set the value of the .Random.seed object in the working directory. .Random.seed gives the state of the random number generation system.

DETAILS:

If no arguments are given to set.seed then the seed is set to a value based on the number of milli- or microseconds since 1970 or the last reboot, depending on the platform. Calling RNGkind(kind) also sets the seed to a time-based value after changing the kind of the random uniform generator. Also, if the dataset .Random.seed does not exist, it will be created the first time a random number is generated. The RNG kind will be set to "default" or to the last value used in the current session and the seed will be set to a time-based value.

Available Random Number Generators:

There are two built-in uniform(0,1) random number generators, "Super-Duper" and "Mersenne-Twister", and one named "user-supplied" that lets you load compiled code implementing a generator of your choice. All the non-uniform(0,1) generators are built to use the chosen uniform(0,1) generator.

Each generator stores its current state in the working database (where=1) as an integer vector called .Random.seed. The first element of .Random.seed generally is a code for the kind of generator, although for compatibility with older versions of Splus which allowed only the "Super-Duper" generator, if the initial value of .Random.seed is less than 100 it is assumed to be for "Super-Duper". The remaining elements of .Random.seed are the state of the chosen generator itself. Each generator uses .Random.seed in different ways and has its own requirements for the values in it, so you should not modify it. You may store it and restore it so you can recreate a given stream of random numbers.

The "Super-Duper" generator is adapted from George Marsaglia's 1973 package of the same name. The low-level integer generator produces a 32-bit integer whose top 31 bits are divided by 2^31 = 2,147,483,648. The result is a real number in the half-open interval [0,1). The 32-bit integer is computed by a bitwise exclusive-or of two additional 32-bit integers: one produced by a congruential generator, and one produced by a Tausworthe generator. For most starting seeds, the congruential and Tausworthe generators combine to give a period of 2^30 * 4,292,868,097, which is approximately 4.6 * 10^18. The S-PLUS version of the generator skips cases in which the result is exactly 0, producing random numbers in the open interval (0,1); this reduces the period by a small amount. .Random.seed stores the base 64 representation of the 32-bit congruential and Tausworthe states as 12 integers in the range 0 through 63.

The "Mersenne-Twister" is adapted from Matsumoto and Nishimura's 2002 version of the Mersenne Twister generator. It has a period of 2^19937-1 (about 10^6001), has a 623-dimensional equidistribution property, and the low-level integer version has 32 random bits. Its state is kept in 625 32 bit integers (the first of which is in the range 1:624), resulting in a .Random.seed of length 626. The Splus version skips cases where the low-level generator would return a 0 (it won't return a 1). This differs from R's implementation, which replaces a 0.0 by a very small positive number.

The "user-supplied" generator requires that the user dynamically load compiled C code with functions by certain fixed names that implement the generator. The protocol is very similar to that explained in "Writing R Extensions" (the user-supplied normal generator is not supported). Splus will skip outputs of the user-supplied random uniform generator that are not in (0,1).

REFERENCES:

Kennedy, W. J. and Gentle, J. E. (1980). Statistical Computing. Marcel Dekker, New York.



Marsaglia, G. et al. (1973). Random Number Package: "Super-Duper". School of Computer Science, McGill University.

M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom number generator", ACM Trans. on Modeling and Computer Simulation Vol. 8, No. 1, January pp.3-30 (1998)

A preprint of that paper can be found at

http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/ARTICLES/mt.pdf



Venables, W.N. & Ripley B.D. (1997). Modern Applied Statistics with S-PLUS (2nd ed.). New York: Springer-Verlag.



R Development Core Team (2008). R: A Language and Environment for Statistical Computing Vienna, Austria: R Foundation for Statistical Computing.

SEE ALSO:

, , , , , , , , , , , , , , , , , .

EXAMPLES:

# to reproduce random samples, start with a time-base random seed: 
set.seed() 
old.seed <- .Random.seed
   # do some work, then reset .Random.seed in working database
.Random.seed <<- old.seed
   # repeat work: the same "random" numbers occur. 
RNGkind("Mersenne-Twister")
# future random numbers will come from the Mersenne-Twister generator

Copyrights:

M. Matsumoto and T. Nishimura generously made the Mersenne Twister code available for free use, even in commercial products. It was available under the GNU Public License until 2001, but the authors changed to a much more liberal licensing policy then. Their copyright notice follows

   A C-program for MT19937, with initialization improved 2002/1/26.
   Coded by Takuji Nishimura and Makoto Matsumoto.

   Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
   All rights reserved.

   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:

     1. Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.

     2. Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.

     3. The names of its contributors may not be used to endorse or promote
        products derived from this software without specific prior written
        permission.

   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   Any feedback is very welcome.
   http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
   email: m-mat @ math.sci.hiroshima-u.ac.jp (remove space)