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 |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 10 | distributions. |
| 11 | For integers, uniform selection from a range. |
| 12 | For sequences, uniform selection of a random element, and a function to |
| 13 | generate a random permutation of a list in-place. |
| 14 | On the real line, there are functions to compute uniform, normal (Gaussian), |
| 15 | lognormal, negative exponential, gamma, and beta distributions. |
| 16 | For generating distribution of angles, the circular uniform and |
| 17 | von Mises distributions are available. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 18 | |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 19 | Almost all module functions depend on the basic function |
| 20 | \function{random()}, which generates a random float uniformly in |
| 21 | the semi-open range [0.0, 1.0). Python uses the standard Wichmann-Hill |
| 22 | generator, combining three pure multiplicative congruential |
| 23 | generators of modulus 30269, 30307 and 30323. Its period (how many |
| 24 | numbers it generates before repeating the sequence exactly) is |
| 25 | 6,953,607,871,644. While of much higher quality than the \function{rand()} |
| 26 | function supplied by most C libraries, the theoretical properties |
| 27 | are much the same as for a single linear congruential generator of |
| 28 | large modulus. |
| 29 | |
| 30 | The functions in this module are not threadsafe: if you want to call these |
| 31 | functions from multiple threads, you should explicitly serialize the calls. |
| 32 | Else, because no critical sections are implemented internally, calls |
| 33 | from different threads may see the same return values. |
| 34 | |
Tim Peters | d7b5e88 | 2001-01-25 03:36:26 +0000 | [diff] [blame^] | 35 | The functions supplied by this module are actually bound methods of a |
| 36 | hidden instance of the \var{random.Random} class. You can instantiate |
| 37 | your own instances of \var{Random} to get generators that don't share state. |
| 38 | This may be especially useful for multi-threaded programs, although there's |
| 39 | no simple way to seed the distinct generators to ensure that the generated |
| 40 | sequences won't overlap. Class \var{Random} can also be subclassed if you |
| 41 | want to use a different basic generator of your own devising: in that |
| 42 | case, override the \method{random()}, \method{seed()}, \method{getstate()} |
| 43 | and \method{setstate()} methods. |
| 44 | |
| 45 | |
| 46 | Bookkeeping functions: |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 47 | |
| 48 | \begin{funcdesc}{seed}{\optional{x}} |
| 49 | Initialize the basic random number generator. |
| 50 | Optional argument \var{x} can be any hashable object, |
| 51 | and the generator is seeded from its hash code. |
| 52 | It is not guaranteed that distinct hash codes will produce distinct |
| 53 | seeds. |
| 54 | If \var{x} is omitted or \code{None}, |
| 55 | the seed is derived from the current system time. |
| 56 | The seed is also set from the current system time when |
| 57 | the module is first imported. |
Barry Warsaw | 8312577 | 2001-01-25 00:39:16 +0000 | [diff] [blame] | 58 | \end{funcdesc} |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 59 | |
Tim Peters | d7b5e88 | 2001-01-25 03:36:26 +0000 | [diff] [blame^] | 60 | \begin{funcdesc}{getstate}{} |
| 61 | Return an object capturing the current internal state of the generator. |
| 62 | This object can be passed to \code{setstate()} to restore the state. |
| 63 | \end{funcdesc} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 64 | |
Tim Peters | d7b5e88 | 2001-01-25 03:36:26 +0000 | [diff] [blame^] | 65 | \begin{funcdesc}{setstate}{state} |
| 66 | \var{state} should have been obtained from a previous call to |
| 67 | \code{getstate()}, and \code{setstate()} restores the internal state |
| 68 | of the generate to what it was at the time \code{setstate()} was called. |
| 69 | \end{funcdesc} |
| 70 | |
| 71 | |
| 72 | Functions for integers: |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 73 | |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 74 | \begin{funcdesc}{randrange}{\optional{start,} stop\optional{, step}} |
| 75 | Return a randomly selected element from \code{range(\var{start}, |
| 76 | \var{stop}, \var{step})}. This is equivalent to |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 77 | \code{choice(range(\var{start}, \var{stop}, \var{step}))}, |
| 78 | but doesn't actually build a range object. |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 79 | \versionadded{1.5.2} |
| 80 | \end{funcdesc} |
| 81 | |
Tim Peters | d7b5e88 | 2001-01-25 03:36:26 +0000 | [diff] [blame^] | 82 | \begin{funcdesc}{randint}{a, b} |
| 83 | \deprecated{2.0}{Use \function{randrange()} instead.} |
| 84 | Return a random integer \var{N} such that |
| 85 | \code{\var{a} <= \var{N} <= \var{b}}. |
| 86 | \end{funcdesc} |
| 87 | |
| 88 | |
| 89 | Functions for sequences: |
| 90 | |
| 91 | \begin{funcdesc}{choice}{seq} |
| 92 | Return a random element from the non-empty sequence \var{seq}. |
| 93 | \end{funcdesc} |
| 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 |
| 98 | returning a random float in [0.0, 1.0); by default, this is the |
| 99 | function \function{random()}. |
| 100 | |
| 101 | Note that for even rather small \code{len(\var{x})}, the total |
| 102 | number of permutations of \var{x} is larger than the period of most |
| 103 | random number generators; this implies that most permutations of a |
| 104 | long sequence can never be generated. |
| 105 | \end{funcdesc} |
| 106 | |
| 107 | |
| 108 | The following functions generate specific real-valued distributions. |
| 109 | Function parameters are named after the corresponding variables in the |
| 110 | distribution's equation, as used in common mathematical practice; most of |
| 111 | these equations can be found in any statistics text. |
| 112 | |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 113 | \begin{funcdesc}{random}{} |
| 114 | Return the next random floating point number in the range [0.0, 1.0). |
| 115 | \end{funcdesc} |
| 116 | |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 117 | \begin{funcdesc}{uniform}{a, b} |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 118 | Return a random real number \var{N} such that |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 119 | \code{\var{a} <= \var{N} < \var{b}}. |
| 120 | \end{funcdesc} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 121 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 122 | \begin{funcdesc}{betavariate}{alpha, beta} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 123 | Beta distribution. Conditions on the parameters are |
| 124 | \code{\var{alpha} > -1} and \code{\var{beta} > -1}. |
| 125 | Returned values range between 0 and 1. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 126 | \end{funcdesc} |
| 127 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 128 | \begin{funcdesc}{cunifvariate}{mean, arc} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 129 | Circular uniform distribution. \var{mean} is the mean angle, and |
| 130 | \var{arc} is the range of the distribution, centered around the mean |
| 131 | angle. Both values must be expressed in radians, and can range |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 132 | between 0 and \emph{pi}. Returned values range between |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 133 | \code{\var{mean} - \var{arc}/2} and \code{\var{mean} + |
| 134 | \var{arc}/2}. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 135 | \end{funcdesc} |
| 136 | |
| 137 | \begin{funcdesc}{expovariate}{lambd} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 138 | Exponential distribution. \var{lambd} is 1.0 divided by the desired |
| 139 | mean. (The parameter would be called ``lambda'', but that is a |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 140 | reserved word in Python.) Returned values range from 0 to |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 141 | positive infinity. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 142 | \end{funcdesc} |
| 143 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 144 | \begin{funcdesc}{gamma}{alpha, beta} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 145 | Gamma distribution. (\emph{Not} the gamma function!) Conditions on |
| 146 | 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] | 147 | \end{funcdesc} |
| 148 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 149 | \begin{funcdesc}{gauss}{mu, sigma} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 150 | Gaussian distribution. \var{mu} is the mean, and \var{sigma} is the |
| 151 | standard deviation. This is slightly faster than the |
| 152 | \function{normalvariate()} function defined below. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 153 | \end{funcdesc} |
| 154 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 155 | \begin{funcdesc}{lognormvariate}{mu, sigma} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 156 | Log normal distribution. If you take the natural logarithm of this |
| 157 | distribution, you'll get a normal distribution with mean \var{mu} |
| 158 | and standard deviation \var{sigma}. \var{mu} can have any value, |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 159 | and \var{sigma} must be greater than zero. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 160 | \end{funcdesc} |
| 161 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 162 | \begin{funcdesc}{normalvariate}{mu, sigma} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 163 | Normal distribution. \var{mu} is the mean, and \var{sigma} is the |
| 164 | standard deviation. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 165 | \end{funcdesc} |
| 166 | |
Fred Drake | 2eda4ca | 1998-03-08 08:13:53 +0000 | [diff] [blame] | 167 | \begin{funcdesc}{vonmisesvariate}{mu, kappa} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 168 | \var{mu} is the mean angle, expressed in radians between 0 and |
| 169 | 2*\emph{pi}, and \var{kappa} is the concentration parameter, which |
| 170 | must be greater than or equal to zero. If \var{kappa} is equal to |
| 171 | zero, this distribution reduces to a uniform random angle over the |
| 172 | range 0 to 2*\emph{pi}. |
Guido van Rossum | 571391b | 1997-04-03 22:41:49 +0000 | [diff] [blame] | 173 | \end{funcdesc} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 174 | |
Guido van Rossum | 4f80b65 | 1997-12-30 17:38:05 +0000 | [diff] [blame] | 175 | \begin{funcdesc}{paretovariate}{alpha} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 176 | Pareto distribution. \var{alpha} is the shape parameter. |
Guido van Rossum | 4f80b65 | 1997-12-30 17:38:05 +0000 | [diff] [blame] | 177 | \end{funcdesc} |
| 178 | |
| 179 | \begin{funcdesc}{weibullvariate}{alpha, beta} |
Fred Drake | 5f0decf | 2001-01-22 18:18:30 +0000 | [diff] [blame] | 180 | Weibull distribution. \var{alpha} is the scale parameter and |
| 181 | \var{beta} is the shape parameter. |
Guido van Rossum | 4f80b65 | 1997-12-30 17:38:05 +0000 | [diff] [blame] | 182 | \end{funcdesc} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 183 | |
Fred Drake | 065cba1 | 2000-12-15 19:07:17 +0000 | [diff] [blame] | 184 | |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 185 | \begin{seealso} |
Tim Peters | 902446a | 2001-01-24 23:06:53 +0000 | [diff] [blame] | 186 | \seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183: |
| 187 | An efficient and portable pseudo-random number generator'', |
| 188 | \citetitle{Applied Statistics} 31 (1982) 188-190.} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 189 | \end{seealso} |