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
  16 The \module{random} module supports the \emph{Random Number
  17 Generator} interface, described in section \ref{rng-objects}.  This
  18 interface of the module, as well as the distribution-specific
  19 functions described below, all use the pseudo-random generator
  20 provided by the \refmodule{whrandom} module.
  21
  22
  23 The following functions are defined to support specific distributions,
  24 and all return real values.  Function parameters are named after the
  25 corresponding variables in the distribution's equation, as used in
  26 common mathematical practice; most of these equations can be found in
  27 any statistics text.  These are expected to become part of the Random
  28 Number Generator interface in a future release.
  29
  30 \begin{funcdesc}{betavariate}{alpha, beta}
  31 Beta distribution.  Conditions on the parameters are
  32 \code{\var{alpha} > -1} and \code{\var{beta} > -1}.
  33 Returned values range between 0 and 1.
  34 \end{funcdesc}
  35
  36 \begin{funcdesc}{cunifvariate}{mean, arc}
  37 Circular uniform distribution.  \var{mean} is the mean angle, and
  38 \var{arc} is the range of the distribution, centered around the mean
  39 angle.  Both values must be expressed in radians, and can range
  40 between 0 and \emph{pi}.  Returned values will range between
  41 \code{\var{mean} - \var{arc}/2} and \code{\var{mean} + \var{arc}/2}.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{expovariate}{lambd}
  45 Exponential distribution.  \var{lambd} is 1.0 divided by the desired
  46 mean.  (The parameter would be called ``lambda'', but that is a
  47 reserved word in Python.)  Returned values will range from 0 to
  48 positive infinity.
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{gamma}{alpha, beta}
  52 Gamma distribution.  (\emph{Not} the gamma function!)  Conditions on
  53 the parameters are \code{\var{alpha} > -1} and \code{\var{beta} > 0}.
  54 \end{funcdesc}
  55
  56 \begin{funcdesc}{gauss}{mu, sigma}
  57 Gaussian distribution.  \var{mu} is the mean, and \var{sigma} is the
  58 standard deviation.  This is slightly faster than the
  59 \function{normalvariate()} function defined below.
  60 \end{funcdesc}
  61
  62 \begin{funcdesc}{lognormvariate}{mu, sigma}
  63 Log normal distribution.  If you take the natural logarithm of this
  64 distribution, you'll get a normal distribution with mean \var{mu} and
  65 standard deviation \var{sigma}.  \var{mu} can have any value, and
  66 \var{sigma} must be greater than zero.
  67 \end{funcdesc}
  68
  69 \begin{funcdesc}{normalvariate}{mu, sigma}
  70 Normal distribution.  \var{mu} is the mean, and \var{sigma} is the
  71 standard deviation.
  72 \end{funcdesc}
  73
  74 \begin{funcdesc}{vonmisesvariate}{mu, kappa}
  75 \var{mu} is the mean angle, expressed in radians between 0 and 2*\emph{pi},
  76 and \var{kappa} is the concentration parameter, which must be greater
  77 than or equal to zero.  If \var{kappa} is equal to zero, this
  78 distribution reduces to a uniform random angle over the range 0 to
  79 2*\emph{pi}.
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{paretovariate}{alpha}
  83 Pareto distribution.  \var{alpha} is the shape parameter.
  84 \end{funcdesc}
  85
  86 \begin{funcdesc}{weibullvariate}{alpha, beta}
  87 Weibull distribution.  \var{alpha} is the scale parameter and
  88 \var{beta} is the shape parameter.
  89 \end{funcdesc}
  90
  91 \begin{seealso}
  92   \seemodule{whrandom}{The standard Python random number generator.}
  93 \end{seealso}
  94
  95
  96 \subsection{The Random Number Generator Interface
  97             \label{rng-objects}}
  98
  99 % XXX This *must* be updated before a future release!
 100
 101 The \dfn{Random Number Generator} interface describes the methods
 102 which are available for all random number generators.  This will be
 103 enhanced in future releases of Python.
 104
 105 In this release of Python, the modules \refmodule{random},
 106 \refmodule{whrandom}, and instances of the
 107 \class{whrandom.whrandom} class all conform to this interface.
 108
 109
 110 \begin{funcdesc}{choice}{seq}
 111 Chooses a random element from the non-empty sequence \var{seq} and
 112 returns it.
 113 \end{funcdesc}
 114
 115 \begin{funcdesc}{randint}{a, b}
 116 \deprecated{2.0}{Use \function{randrange()} instead.}
 117 Returns a random integer \var{N} such that
 118 \code{\var{a} <= \var{N} <= \var{b}}.
 119 \end{funcdesc}
 120
 121 \begin{funcdesc}{random}{}
 122 Returns the next random floating point number in the range [0.0
 123 ... 1.0).
 124 \end{funcdesc}
 125
 126 \begin{funcdesc}{randrange}{\optional{start,} stop\optional{, step}}
 127 Return a randomly selected element from \code{range(\var{start},
 128 \var{stop}, \var{step})}.  This is equivalent to
 129 \code{choice(range(\var{start}, \var{stop}, \var{step}))}.
 130 \versionadded{1.5.2}
 131 \end{funcdesc}
 132
 133 \begin{funcdesc}{uniform}{a, b}
 134 Returns a random real number \var{N} such that
 135 \code{\var{a} <= \var{N} < \var{b}}.
 136 \end{funcdesc}