Doc/lib/librandom.tex

   1 \section{\module{random} ---
   2          Generate pseudo-random numbers}
   3
   4 \declaremodule{standard}{random}
   5 \modulesynopsis{Generate pseudo-random numbers with various common
   6                 distributions.}
   7
   8
   9 This module implements pseudo-random number generators for various
  10 distributions: on the real line, there are functions to compute normal
  11 or Gaussian, lognormal, negative exponential, gamma, and beta
  12 distributions.  For generating distribution of angles, the circular
  13 uniform and von Mises distributions are available.
  14
  15 The module exports the following functions, which are exactly
  16 equivalent to those in the \refmodule{whrandom} module:
  17 \function{choice()}, \function{randint()}, \function{random()} and
  18 \function{uniform()}.  See the documentation for the
  19 \refmodule{whrandom} module for these functions.
  20
  21 The following functions specific to the \module{random} module are also
  22 defined, and all return real values.  Function parameters are named
  23 after the corresponding variables in the distribution's equation, as
  24 used in common mathematical practice; most of these equations can be
  25 found in any statistics text.
  26
  27 \begin{funcdesc}{betavariate}{alpha, beta}
  28 Beta distribution.  Conditions on the parameters are
  29 \code{\var{alpha} >- 1} and \code{\var{beta} > -1}.
  30 Returned values will range between 0 and 1.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{cunifvariate}{mean, arc}
  34 Circular uniform distribution.  \var{mean} is the mean angle, and
  35 \var{arc} is the range of the distribution, centered around the mean
  36 angle.  Both values must be expressed in radians, and can range
  37 between 0 and \emph{pi}.  Returned values will range between
  38 \code{\var{mean} - \var{arc}/2} and \code{\var{mean} + \var{arc}/2}.
  39 \end{funcdesc}
  40
  41 \begin{funcdesc}{expovariate}{lambd}
  42 Exponential distribution.  \var{lambd} is 1.0 divided by the desired
  43 mean.  (The parameter would be called ``lambda'', but that is a
  44 reserved word in Python.)  Returned values will range from 0 to
  45 positive infinity.
  46 \end{funcdesc}
  47
  48 \begin{funcdesc}{gamma}{alpha, beta}
  49 Gamma distribution.  (\emph{Not} the gamma function!)  Conditions on
  50 the parameters are \code{\var{alpha} > -1} and \code{\var{beta} > 0}.
  51 \end{funcdesc}
  52
  53 \begin{funcdesc}{gauss}{mu, sigma}
  54 Gaussian distribution.  \var{mu} is the mean, and \var{sigma} is the
  55 standard deviation.  This is slightly faster than the
  56 \function{normalvariate()} function defined below.
  57 \end{funcdesc}
  58
  59 \begin{funcdesc}{lognormvariate}{mu, sigma}
  60 Log normal distribution.  If you take the natural logarithm of this
  61 distribution, you'll get a normal distribution with mean \var{mu} and
  62 standard deviation \var{sigma}.  \var{mu} can have any value, and \var{sigma}
  63 must be greater than zero.
  64 \end{funcdesc}
  65
  66 \begin{funcdesc}{normalvariate}{mu, sigma}
  67 Normal distribution.  \var{mu} is the mean, and \var{sigma} is the
  68 standard deviation.
  69 \end{funcdesc}
  70
  71 \begin{funcdesc}{vonmisesvariate}{mu, kappa}
  72 \var{mu} is the mean angle, expressed in radians between 0 and 2*\emph{pi},
  73 and \var{kappa} is the concentration parameter, which must be greater
  74 than or equal to zero.  If \var{kappa} is equal to zero, this
  75 distribution reduces to a uniform random angle over the range 0 to
  76 2*\emph{pi}.
  77 \end{funcdesc}
  78
  79 \begin{funcdesc}{paretovariate}{alpha}
  80 Pareto distribution.  \var{alpha} is the shape parameter.
  81 \end{funcdesc}
  82
  83 \begin{funcdesc}{weibullvariate}{alpha, beta}
  84 Weibull distribution.  \var{alpha} is the scale parameter and
  85 \var{beta} is the shape parameter.
  86 \end{funcdesc}
  87
  88 \begin{seealso}
  89   \seemodule{whrandom}{the standard Python random number generator}
  90 \end{seealso}