Random                 package:base                 R Documentation

Random Number Generation

Description:

     `.Random.seed' is an integer vector, containing the random number
     generator (RNG) state for random number generation in R. It can be
     saved and restored, but should not be altered by the user.

     `RNGkind' is a more friendly interface to query or set the kind of
     RNG in use.

     `set.seed' is the recommended way to specify seeds.

Usage:

     .Random.seed <- c(rng.kind, n1, n2, ...)
     save.seed <- .Random.seed

     RNGkind(kind = NULL, normal.kind = NULL)
     set.seed(seed, kind = NULL)

Arguments:

    kind: character or `NULL'.  If `kind' is a character string, set
          R's RNG to the kind desired. If it is `NULL', return the
          currently used RNG. Use `"default"' to return to the R
          default.

normal.kind: character string or `NULL'.  If it is a character string,
          set the method of Normal generation. Use `"default"' to
          return to the R default.

    seed: a single value, interpreted as an integer.

rng.kind: integer code in `0:k' for the above `kind'.

n1, n2, ...: integers. See the details for how many are required (which
          depends on `rng.kind').

Details:

     The currently available RNG kinds are given below.  `kind' is
     partially matched to this list.  The default is
     `"Marsaglia-Multicarry"'.

     `"Wichmann-Hill"' The seed, `.Random.seed[-1] == r[1:3]' is an
          integer vector of length 3, where each `r[i]' is in `1:(p[i]
          - 1)', where `p' is the length 3 vector of primes, `p =
          (30269, 30307, 30323)'. The Wichmann-Hill generator has a
          cycle length of 6.9536e12 (= `prod(p-1)/4', see Applied
          Statistics (1984) 33, 123 which corrects the original
          article).

     `"Marsaglia-Multicarry"': A multiply-with-carry RNG is used, as
          recommended by George Marsaglia in his post to the mailing
          list `sci.stat.math'. It has a period of more than 2^60 and
          has passed all tests (according to Marsaglia).  The seed is
          two integers (all values allowed).

     `"Super-Duper"': Marsaglia's famous Super-Duper from the 70's. 
          This is the original version which does not pass the MTUPLE
          test of the Diehard battery.  It has a period of about
          4.6*10^18 for most initial seeds.  The seed is two integers
          (all values allowed for the first seed: the second must be
          odd).

          We use the implementation by Reeds et al. (1982-84).

          The two seeds are the Tausworthe and congruence long
          integers, respectively.  A one-to-one mapping to S's
          `.Random.seed[1:12]' is possible but we will not publish one,
          not least as this generator is not exactly the same as that
          in recent versions of S-PLUS.

     `"Mersenne-Twister":' From Matsumoto and Nishimura (1998). A
          twisted GFSR with period 2^19937 - 1 and equidistribution in
          623 consecutive dimensions (over the whole period).  The
          ``seed'' is a 624-dimensional set of 32-bit integers plus a
          current position in that set.

     `"Knuth-TAOCP":' From Knuth (1997).  A GFSR using lagged Fibonacci
          sequences with subtraction. That is, the recurrence used is

                 X[j] = (X[j-100] - X[j-37]) mod 2^30

          and the ``seed'' is the set of the 100 last numbers (actually
          recorded as 101 numbers, the last being a cyclic shift of the
          buffer).  The period is around 2^129.

     `"user-supplied":' Use a user-supplied generator. See
          `Random.user' for details.

     `normal.kind' can be `"Kinderman-Ramage"' (the default) or
     `"Ahrens-Dieter"' or `"Box-Muller"' or `"user-supplied"'.

     `set.seed' uses its single integer argument to set as many seeds
     as are required.  It is intended as a simple way to get quite
     different seeds by specifying small integer arguments, and also as
     a way to get valid seed sets for the more complicated methods
     (especially `"Knuth-TAOCP"').

Value:

     `.Random.seed' is an `integer' vector whose first element codes
     the kind of RNG and normal generator. The lowest two decimal
     digits are in in `0:(k-1)' where `k' is the number of available
     RNGs. The hundreds represent the type of normal generator
     (starting at `0').

     In the underlying C, `.Random.seed[-1]' is `unsigned'; therefore
     in R `.Random.seed[-1]' can be negative.

     `RNGkind' returns a two-element character vector of the RNG and
     normal kinds in use before the call, invisibly if either argument
     is not `NULL'.

     `set.seed' returns `NULL', invisibly.

Note:

     Initially, there is no seed;  a new one is created from the
     current time when one is required.  Hence, different sessions will
     give different simulation results, by default.

     `.Random.seed' saves the seed set for the uniform random-number
     generator, at least for the system generators.  It does not
     necessarily save the state of other generators, and in particular
     does not save the state of the Box-Muller normal generator.  If
     you want to reproduce work later, call `set.seed' rather than set
     `.Random.seed'.

Author(s):

     of RNGkind: Martin Maechler. Current implementation, B. D. Ripley

References:

     Wichmann, B. A.  and Hill, I. D. (1982) Algorithm AS 183: An
     Efficient and Portable Pseudo-random Number Generator, Applied
     Statistics, 31, 188-190; Remarks: 34, 198 and 35, 89.

     De Matteis, A. and Pagnutti, S. (1993) Long-range Correlation
     Analysis of the Wichmann-Hill Random Number Generator, Statist.
     Comput., 3, 67-70.

     Marsaglia, G. (1997) A random number generator for C. Discussion
     paper, posting on Usenet newsgroup `sci.stat.math' on September
     29, 1997.

     Reeds, J., Hubert, S. and Abrahams, M. (1982-4) C implementation
     of SuperDuper, University of California at Berkeley.  (Personal
     communication from Jim Reeds to Ross Ihaka.)

     Marsaglia, G. and Zaman, A. (1994) Some portable very-long-period
     random number generators. Computers in Physics, 8, 117-121.

     Matsumoto, M. and Nishimura, T. (1998) Mersenne Twister: A
     623-dimensionally equidistributed uniform pseudo-random number
     generator, ACM Transactions on Modeling and Computer Simulation,
     8, 3-30.
     Source code at <URL:
     http://www.math.keio.ac.jp/~matumoto/emt.html>.

     Knuth, D. E. (1997) The Art of Computer Programming. Volume 2,
     third edition.
     Source code at <URL:
     http://www-cs-faculty.stanford.edu/~knuth/taocp.html>.

See Also:

     `runif', `rnorm', ....

Examples:

     runif(1); .Random.seed; runif(1); .Random.seed
     ## If there is no seed,  a ``random'' new one is created:
     rm(.Random.seed); runif(1); .Random.seed

     RNGkind("Wich")# (partial string matching on 'kind')

     ## This shows how `runif(.)' works for Wichmann-Hill,
     ## using only R functions:

     p.WH <- c(30269, 30307, 30323)
     a.WH <- c(  171,   172,   170)
     next.WHseed <- function(i.seed = .Random.seed[-1])
       { (a.WH * i.seed) %% p.WH }
     my.runif1 <- function(i.seed = .Random.seed)
       { ns <- next.WHseed(i.seed[-1]); sum(ns / p.WH) %% 1 }
     rs <- .Random.seed
     (WHs <- next.WHseed(rs[-1]))
     u <- runif(1)
     stopifnot(
      next.WHseed(rs[-1]) == .Random.seed[-1],
      all.equal(u, my.runif1(rs))
     )

     ## ----
     .Random.seed
     ok <- RNGkind()
     RNGkind("Super")#matches  "Super-Duper"
     RNGkind()
     .Random.seed # new, corresponding to  Super-Duper

     ## Reset:
     RNGkind(ok[1])

