Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{random} --- |
Fred Drake | 048b75b | 1999-04-21 18:14:22 +0000 | [diff] [blame] | 2 | Generate pseudo-random numbers} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | 048b75b | 1999-04-21 18:14:22 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{random} |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 5 | \modulesynopsis{Generate pseudo-random numbers with various common |
Fred Drake | 048b75b | 1999-04-21 18:14:22 +0000 | [diff] [blame] | 6 | distributions.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 7 | |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 15 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 29 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 30 | \begin{funcdesc}{betavariate}{alpha, beta} |
| 31 | Beta distribution. Conditions on the parameters are |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 32 | \code{\var{alpha} > -1} and \code{\var{beta} > -1}. |
| 33 | Returned values range between 0 and 1. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 34 | \end{funcdesc} |
| 35 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 36 | \begin{funcdesc}{cunifvariate}{mean, arc} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 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 |
Fred Drake | 048b75b | 1999-04-21 18:14:22 +0000 | [diff] [blame] | 40 | between 0 and \emph{pi}. Returned values will range between |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 41 | \code{\var{mean} - \var{arc}/2} and \code{\var{mean} + \var{arc}/2}. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 42 | \end{funcdesc} |
| 43 | |
| 44 | \begin{funcdesc}{expovariate}{lambd} |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 49 | \end{funcdesc} |
| 50 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 51 | \begin{funcdesc}{gamma}{alpha, beta} |
| 52 | Gamma distribution. (\emph{Not} the gamma function!) Conditions on |
Fred Drake | 4e66887 | 1998-04-03 06:04:12 +0000 | [diff] [blame] | 53 | the parameters are \code{\var{alpha} > -1} and \code{\var{beta} > 0}. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 54 | \end{funcdesc} |
| 55 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 56 | \begin{funcdesc}{gauss}{mu, sigma} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 57 | Gaussian distribution. \var{mu} is the mean, and \var{sigma} is the |
| 58 | standard deviation. This is slightly faster than the |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 59 | \function{normalvariate()} function defined below. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 60 | \end{funcdesc} |
| 61 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 62 | \begin{funcdesc}{lognormvariate}{mu, sigma} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 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 |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 65 | standard deviation \var{sigma}. \var{mu} can have any value, and |
| 66 | \var{sigma} must be greater than zero. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 67 | \end{funcdesc} |
| 68 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 69 | \begin{funcdesc}{normalvariate}{mu, sigma} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 70 | Normal distribution. \var{mu} is the mean, and \var{sigma} is the |
| 71 | standard deviation. |
| 72 | \end{funcdesc} |
| 73 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 74 | \begin{funcdesc}{vonmisesvariate}{mu, kappa} |
Fred Drake | 048b75b | 1999-04-21 18:14:22 +0000 | [diff] [blame] | 75 | \var{mu} is the mean angle, expressed in radians between 0 and 2*\emph{pi}, |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 76 | and \var{kappa} is the concentration parameter, which must be greater |
Guido van Rossum | a933f6a | 1998-04-20 14:43:44 +0000 | [diff] [blame] | 77 | than or equal to zero. If \var{kappa} is equal to zero, this |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 78 | distribution reduces to a uniform random angle over the range 0 to |
Fred Drake | 048b75b | 1999-04-21 18:14:22 +0000 | [diff] [blame] | 79 | 2*\emph{pi}. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 80 | \end{funcdesc} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 81 | |
Guido van Rossum | 4f80b65 | 1997-12-30 17:38:05 +0000 | [diff] [blame] | 82 | \begin{funcdesc}{paretovariate}{alpha} |
| 83 | Pareto distribution. \var{alpha} is the shape parameter. |
| 84 | \end{funcdesc} |
| 85 | |
| 86 | \begin{funcdesc}{weibullvariate}{alpha, beta} |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 87 | Weibull distribution. \var{alpha} is the scale parameter and |
Guido van Rossum | 4f80b65 | 1997-12-30 17:38:05 +0000 | [diff] [blame] | 88 | \var{beta} is the shape parameter. |
| 89 | \end{funcdesc} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 90 | |
Fred Drake | 065cba1 | 2000-12-15 19:07:17 +0000 | [diff] [blame^] | 91 | |
| 92 | This function does not represent a specific distribution, but |
| 93 | implements a standard useful algorithm: |
| 94 | |
| 95 | \begin{funcdesc}{shuffle}{x\optional{, random}} |
| 96 | Shuffle the sequence \var{x} in place. |
| 97 | The optional argument \var{random} is a 0-argument function returning |
| 98 | a random float in [0.0, 1.0); by default, this is the function |
| 99 | \function{random()}. |
| 100 | |
| 101 | Note that for even rather small \code{len(\var{x})}, the total number |
| 102 | of permutations of \var{x} is larger than the period of most random |
| 103 | number generators; this implies that most permutations of a long |
| 104 | sequence can never be generated. |
| 105 | \end{funcdesc} |
| 106 | |
| 107 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 108 | \begin{seealso} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 109 | \seemodule{whrandom}{The standard Python random number generator.} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 110 | \end{seealso} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 111 | |
| 112 | |
| 113 | \subsection{The Random Number Generator Interface |
| 114 | \label{rng-objects}} |
| 115 | |
| 116 | % XXX This *must* be updated before a future release! |
| 117 | |
| 118 | The \dfn{Random Number Generator} interface describes the methods |
| 119 | which are available for all random number generators. This will be |
| 120 | enhanced in future releases of Python. |
| 121 | |
| 122 | In this release of Python, the modules \refmodule{random}, |
| 123 | \refmodule{whrandom}, and instances of the |
| 124 | \class{whrandom.whrandom} class all conform to this interface. |
| 125 | |
| 126 | |
| 127 | \begin{funcdesc}{choice}{seq} |
| 128 | Chooses a random element from the non-empty sequence \var{seq} and |
| 129 | returns it. |
| 130 | \end{funcdesc} |
| 131 | |
| 132 | \begin{funcdesc}{randint}{a, b} |
Fred Drake | f0e8898 | 2000-06-30 15:32:31 +0000 | [diff] [blame] | 133 | \deprecated{2.0}{Use \function{randrange()} instead.} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 134 | Returns a random integer \var{N} such that |
| 135 | \code{\var{a} <= \var{N} <= \var{b}}. |
| 136 | \end{funcdesc} |
| 137 | |
| 138 | \begin{funcdesc}{random}{} |
| 139 | Returns the next random floating point number in the range [0.0 |
| 140 | ... 1.0). |
| 141 | \end{funcdesc} |
| 142 | |
Fred Drake | f0e8898 | 2000-06-30 15:32:31 +0000 | [diff] [blame] | 143 | \begin{funcdesc}{randrange}{\optional{start,} stop\optional{, step}} |
| 144 | Return a randomly selected element from \code{range(\var{start}, |
| 145 | \var{stop}, \var{step})}. This is equivalent to |
| 146 | \code{choice(range(\var{start}, \var{stop}, \var{step}))}. |
| 147 | \versionadded{1.5.2} |
| 148 | \end{funcdesc} |
| 149 | |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 150 | \begin{funcdesc}{uniform}{a, b} |
| 151 | Returns a random real number \var{N} such that |
| 152 | \code{\var{a} <= \var{N} < \var{b}}. |
| 153 | \end{funcdesc} |