Doc/lib/libwhrandom.tex

   1 \section{\module{whrandom} ---
   2          Pseudo-random number generator}
   3
   4 \declaremodule{standard}{whrandom}
   5 \modulesynopsis{Floating point pseudo-random number generator.}
   6
   7 \deprecated{2.1}{Use \refmodule{random} instead.}
   8
   9 \strong{Note:}  This module was an implementation detail of the
  10 \refmodule{random} module in releases of Python prior to 2.1.  It is
  11 no longer used.  Please do not use this module directly; use
  12 \refmodule{random} instead.
  13
  14 This module implements a Wichmann-Hill pseudo-random number generator
  15 class that is also named \class{whrandom}.  Instances of the
  16 \class{whrandom} class conform to the Random Number Generator
  17 interface described in section \ref{rng-objects}.  They also offer the
  18 following method, specific to the Wichmann-Hill algorithm:
  19
  20 \begin{methoddesc}[whrandom]{seed}{\optional{x, y, z}}
  21   Initializes the random number generator from the integers \var{x},
  22   \var{y} and \var{z}.  When the module is first imported, the random
  23   number is initialized using values derived from the current time.
  24   If \var{x}, \var{y}, and \var{z} are either omitted or \code{0}, the
  25   seed will be computed from the current system time.  If one or two
  26   of the parameters are \code{0}, but not all three, the zero values
  27   are replaced by ones.  This causes some apparently different seeds
  28   to be equal, with the corresponding result on the pseudo-random
  29   series produced by the generator.
  30 \end{methoddesc}
  31
  32 \begin{funcdesc}{choice}{seq}
  33 Chooses a random element from the non-empty sequence \var{seq} and returns it.
  34 \end{funcdesc}
  35
  36 \begin{funcdesc}{randint}{a, b}
  37 Returns a random integer \var{N} such that \code{\var{a}<=\var{N}<=\var{b}}.
  38 \end{funcdesc}
  39
  40 \begin{funcdesc}{random}{}
  41 Returns the next random floating point number in the range [0.0 ... 1.0).
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{seed}{x, y, z}
  45 Initializes the random number generator from the integers \var{x},
  46 \var{y} and \var{z}.  When the module is first imported, the random
  47 number is initialized using values derived from the current time.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{uniform}{a, b}
  51 Returns a random real number \var{N} such that \code{\var{a}<=\var{N}<\var{b}}.
  52 \end{funcdesc}
  53
  54 When imported, the \module{whrandom} module also creates an instance of
  55 the \class{whrandom} class, and makes the methods of that instance
  56 available at the module level.  Therefore one can write either
  57 \code{N = whrandom.random()} or:
  58
  59 \begin{verbatim}
  60 generator = whrandom.whrandom()
  61 N = generator.random()
  62 \end{verbatim}
  63
  64 Note that using separate instances of the generator leads to
  65 independent sequences of pseudo-random numbers.
  66
  67 \begin{seealso}
  68   \seemodule{random}{Generators for various random distributions and
  69                      documentation for the Random Number Generator
  70                      interface.}
  71   \seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183:
  72            An efficient and portable pseudo-random number generator'',
  73            \citetitle{Applied Statistics} 31 (1982) 188-190.}
  74 \end{seealso}