

   RRaannddoomm NNuummbbeerr GGeenneerraattiioonn

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

        RNGkind(kind=NULL)

   AArrgguummeennttss::

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

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

   n1,n2,...: integers.

   DDeessccrriippttiioonn::

        `.Random.seed' is an integer vector, containing the
        random number generator (RNG) state for random number
        generation in R.

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

   DDeettaaiillss::

        Currently available RNG kinds

           * "Wichmann-Hill": `.Random.seed[1] == 0'

        The seed, `.Random.seed[-1] == r[1:3]' is an integer
        vector of length 3, where each `r[i]' is in `1:p[i]',
        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
        p.123 of Applied Statistics (1984) vol.33 which cor-
        rects the original article.

      * "Marsaglia-Multicarry": `.Random.seed[1] == 1'

        A multiply-with-carry RNG is used, as recommended by
        George Marsaglia in his post to the mailing list
        `sci.stat.math' on September 29, 1997.  It has a period
        of > 2^60 and has passed all tests (according to
        Marsaglia).

      * "Super-Duper": `.Random.seed[1] == 2'

        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
        4.6*10^18.

        We use the implementation as by Reeds et al.
        (1982-'83), with the additional non-0 seed measure (see
        note below).

        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 hasn't been done
        yet.

        -- -- to be expanded -- --

        ((Planned additions are "Mersenne-Twister", "Knuth-
        TAOCP" (from TAOCP, Vol.2, 3rd ed.,1997), "Ecuyer-...",
        "Eichenauer-..."))

        Note: If any of `.Random.seed[i]' (i>1) is set to `0',
        it will be substituted with `1', in the next call to a
        random number generator, such as `runif'.

   VVaalluuee::

        `.Random.seed' is an `integer' vector whose first ele-
        ment codes the kind of RNG and therefore is in `0:k'
        where {k+1} is the number of available RNGs.

        In the underlying C, `.Random.seed[-1]' is used as
        `unsigned long' (32 bits at least); in R, whose `inte-
        ger's are C's `long', `.Random.seed[i]' can therefore
        be negative for i > 1.

        `RNGkind' returns the RNG in use before the call,
        invisibly if `kind' isn't `NULL'.

   NNoottee::

        Initially, there is no seed;  a new one is created,
        using ``Randomize''.  Hence, student exercises will
        each have different simulation results, by default.

   AAuutthhoorr((ss))::

        of RNGkind: Martin Maechler

   RReeffeerreenncceess::

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

        A. De Matteis and S. Pagnutti (1993).  Long-range Cor-
        relation 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'.

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

   SSeeee AAllssoo::

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

   EExxaammpplleess::

        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')
        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 }

        ## This shows how `runif(.)' works for Wichmann-Hill, using only R functions:
        rs <- .Random.seed
        (WHs <- next.WHseed(rs[-1]))
        u <- runif(1)
        all(next.WHseed(rs[-1]) == .Random.seed[-1])
        u == my.runif1(rs)

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

        ## Reset:
        RNGkind(ok)

