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