Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | |
| 2 | :mod:`random` --- Generate pseudo-random numbers |
| 3 | ================================================ |
| 4 | |
| 5 | .. module:: random |
| 6 | :synopsis: Generate pseudo-random numbers with various common distributions. |
| 7 | |
| 8 | |
| 9 | This module implements pseudo-random number generators for various |
| 10 | distributions. |
| 11 | |
| 12 | For integers, uniform selection from a range. For sequences, uniform selection |
| 13 | of a random element, a function to generate a random permutation of a list |
| 14 | in-place, and a function for random sampling without replacement. |
| 15 | |
| 16 | On the real line, there are functions to compute uniform, normal (Gaussian), |
| 17 | lognormal, negative exponential, gamma, and beta distributions. For generating |
| 18 | distributions of angles, the von Mises distribution is available. |
| 19 | |
| 20 | Almost all module functions depend on the basic function :func:`random`, which |
| 21 | generates a random float uniformly in the semi-open range [0.0, 1.0). Python |
| 22 | uses the Mersenne Twister as the core generator. It produces 53-bit precision |
| 23 | floats and has a period of 2\*\*19937-1. The underlying implementation in C is |
| 24 | both fast and threadsafe. The Mersenne Twister is one of the most extensively |
| 25 | tested random number generators in existence. However, being completely |
| 26 | deterministic, it is not suitable for all purposes, and is completely unsuitable |
| 27 | for cryptographic purposes. |
| 28 | |
| 29 | The functions supplied by this module are actually bound methods of a hidden |
| 30 | instance of the :class:`random.Random` class. You can instantiate your own |
Raymond Hettinger | 28de64f | 2008-01-13 23:40:30 +0000 | [diff] [blame^] | 31 | instances of :class:`Random` to get generators that don't share state. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 32 | |
| 33 | Class :class:`Random` can also be subclassed if you want to use a different |
| 34 | basic generator of your own devising: in that case, override the :meth:`random`, |
Raymond Hettinger | 28de64f | 2008-01-13 23:40:30 +0000 | [diff] [blame^] | 35 | :meth:`seed`, :meth:`getstate`, and :meth:`setstate`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | Optionally, a new generator can supply a :meth:`getrandombits` method --- this |
| 37 | allows :meth:`randrange` to produce selections over an arbitrarily large range. |
| 38 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | Bookkeeping functions: |
| 41 | |
| 42 | |
| 43 | .. function:: seed([x]) |
| 44 | |
| 45 | Initialize the basic random number generator. Optional argument *x* can be any |
Guido van Rossum | 2cc30da | 2007-11-02 23:46:40 +0000 | [diff] [blame] | 46 | :term:`hashable` object. If *x* is omitted or ``None``, current system time is used; |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | current system time is also used to initialize the generator when the module is |
| 48 | first imported. If randomness sources are provided by the operating system, |
| 49 | they are used instead of the system time (see the :func:`os.urandom` function |
| 50 | for details on availability). |
| 51 | |
Georg Brandl | 5c10664 | 2007-11-29 17:41:05 +0000 | [diff] [blame] | 52 | If *x* is not ``None`` or an int, ``hash(x)`` is used instead. If *x* is an |
| 53 | int, *x* is used directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | |
| 55 | |
| 56 | .. function:: getstate() |
| 57 | |
| 58 | Return an object capturing the current internal state of the generator. This |
| 59 | object can be passed to :func:`setstate` to restore the state. |
| 60 | |
Christian Heimes | cbf3b5c | 2007-12-03 21:02:03 +0000 | [diff] [blame] | 61 | State values produced in Python 2.6 cannot be loaded into earlier versions. |
| 62 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 63 | |
| 64 | .. function:: setstate(state) |
| 65 | |
| 66 | *state* should have been obtained from a previous call to :func:`getstate`, and |
| 67 | :func:`setstate` restores the internal state of the generator to what it was at |
| 68 | the time :func:`setstate` was called. |
| 69 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | .. function:: getrandbits(k) |
| 72 | |
Georg Brandl | 5c10664 | 2007-11-29 17:41:05 +0000 | [diff] [blame] | 73 | Returns a python integer with *k* random bits. This method is supplied with |
| 74 | the MersenneTwister generator and some other generators may also provide it |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | as an optional part of the API. When available, :meth:`getrandbits` enables |
| 76 | :meth:`randrange` to handle arbitrarily large ranges. |
| 77 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
| 79 | Functions for integers: |
| 80 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | .. function:: randrange([start,] stop[, step]) |
| 82 | |
| 83 | Return a randomly selected element from ``range(start, stop, step)``. This is |
| 84 | equivalent to ``choice(range(start, stop, step))``, but doesn't actually build a |
| 85 | range object. |
| 86 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
| 88 | .. function:: randint(a, b) |
| 89 | |
| 90 | Return a random integer *N* such that ``a <= N <= b``. |
| 91 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 93 | Functions for sequences: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | |
| 95 | .. function:: choice(seq) |
| 96 | |
| 97 | Return a random element from the non-empty sequence *seq*. If *seq* is empty, |
| 98 | raises :exc:`IndexError`. |
| 99 | |
| 100 | |
| 101 | .. function:: shuffle(x[, random]) |
| 102 | |
| 103 | Shuffle the sequence *x* in place. The optional argument *random* is a |
| 104 | 0-argument function returning a random float in [0.0, 1.0); by default, this is |
| 105 | the function :func:`random`. |
| 106 | |
| 107 | Note that for even rather small ``len(x)``, the total number of permutations of |
| 108 | *x* is larger than the period of most random number generators; this implies |
| 109 | that most permutations of a long sequence can never be generated. |
| 110 | |
| 111 | |
| 112 | .. function:: sample(population, k) |
| 113 | |
| 114 | Return a *k* length list of unique elements chosen from the population sequence. |
| 115 | Used for random sampling without replacement. |
| 116 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 117 | Returns a new list containing elements from the population while leaving the |
| 118 | original population unchanged. The resulting list is in selection order so that |
| 119 | all sub-slices will also be valid random samples. This allows raffle winners |
| 120 | (the sample) to be partitioned into grand prize and second place winners (the |
| 121 | subslices). |
| 122 | |
Guido van Rossum | 2cc30da | 2007-11-02 23:46:40 +0000 | [diff] [blame] | 123 | Members of the population need not be :term:`hashable` or unique. If the population |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | contains repeats, then each occurrence is a possible selection in the sample. |
| 125 | |
| 126 | To choose a sample from a range of integers, use an :func:`range` object as an |
| 127 | argument. This is especially fast and space efficient for sampling from a large |
| 128 | population: ``sample(range(10000000), 60)``. |
| 129 | |
| 130 | The following functions generate specific real-valued distributions. Function |
| 131 | parameters are named after the corresponding variables in the distribution's |
| 132 | equation, as used in common mathematical practice; most of these equations can |
| 133 | be found in any statistics text. |
| 134 | |
| 135 | |
| 136 | .. function:: random() |
| 137 | |
| 138 | Return the next random floating point number in the range [0.0, 1.0). |
| 139 | |
| 140 | |
| 141 | .. function:: uniform(a, b) |
| 142 | |
| 143 | Return a random floating point number *N* such that ``a <= N < b``. |
| 144 | |
| 145 | |
| 146 | .. function:: betavariate(alpha, beta) |
| 147 | |
| 148 | Beta distribution. Conditions on the parameters are ``alpha > 0`` and ``beta > |
| 149 | 0``. Returned values range between 0 and 1. |
| 150 | |
| 151 | |
| 152 | .. function:: expovariate(lambd) |
| 153 | |
| 154 | Exponential distribution. *lambd* is 1.0 divided by the desired mean. (The |
| 155 | parameter would be called "lambda", but that is a reserved word in Python.) |
| 156 | Returned values range from 0 to positive infinity. |
| 157 | |
| 158 | |
| 159 | .. function:: gammavariate(alpha, beta) |
| 160 | |
| 161 | Gamma distribution. (*Not* the gamma function!) Conditions on the parameters |
| 162 | are ``alpha > 0`` and ``beta > 0``. |
| 163 | |
| 164 | |
| 165 | .. function:: gauss(mu, sigma) |
| 166 | |
| 167 | Gaussian distribution. *mu* is the mean, and *sigma* is the standard deviation. |
| 168 | This is slightly faster than the :func:`normalvariate` function defined below. |
| 169 | |
| 170 | |
| 171 | .. function:: lognormvariate(mu, sigma) |
| 172 | |
| 173 | Log normal distribution. If you take the natural logarithm of this |
| 174 | distribution, you'll get a normal distribution with mean *mu* and standard |
| 175 | deviation *sigma*. *mu* can have any value, and *sigma* must be greater than |
| 176 | zero. |
| 177 | |
| 178 | |
| 179 | .. function:: normalvariate(mu, sigma) |
| 180 | |
| 181 | Normal distribution. *mu* is the mean, and *sigma* is the standard deviation. |
| 182 | |
| 183 | |
| 184 | .. function:: vonmisesvariate(mu, kappa) |
| 185 | |
| 186 | *mu* is the mean angle, expressed in radians between 0 and 2\*\ *pi*, and *kappa* |
| 187 | is the concentration parameter, which must be greater than or equal to zero. If |
| 188 | *kappa* is equal to zero, this distribution reduces to a uniform random angle |
| 189 | over the range 0 to 2\*\ *pi*. |
| 190 | |
| 191 | |
| 192 | .. function:: paretovariate(alpha) |
| 193 | |
| 194 | Pareto distribution. *alpha* is the shape parameter. |
| 195 | |
| 196 | |
| 197 | .. function:: weibullvariate(alpha, beta) |
| 198 | |
| 199 | Weibull distribution. *alpha* is the scale parameter and *beta* is the shape |
| 200 | parameter. |
| 201 | |
| 202 | |
| 203 | Alternative Generators: |
| 204 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 205 | .. class:: SystemRandom([seed]) |
| 206 | |
| 207 | Class that uses the :func:`os.urandom` function for generating random numbers |
| 208 | from sources provided by the operating system. Not available on all systems. |
| 209 | Does not rely on software state and sequences are not reproducible. Accordingly, |
| 210 | the :meth:`seed` and :meth:`jumpahead` methods have no effect and are ignored. |
| 211 | The :meth:`getstate` and :meth:`setstate` methods raise |
| 212 | :exc:`NotImplementedError` if called. |
| 213 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 214 | |
| 215 | Examples of basic usage:: |
| 216 | |
| 217 | >>> random.random() # Random float x, 0.0 <= x < 1.0 |
| 218 | 0.37444887175646646 |
| 219 | >>> random.uniform(1, 10) # Random float x, 1.0 <= x < 10.0 |
| 220 | 1.1800146073117523 |
| 221 | >>> random.randint(1, 10) # Integer from 1 to 10, endpoints included |
| 222 | 7 |
| 223 | >>> random.randrange(0, 101, 2) # Even integer from 0 to 100 |
| 224 | 26 |
| 225 | >>> random.choice('abcdefghij') # Choose a random element |
| 226 | 'c' |
| 227 | |
| 228 | >>> items = [1, 2, 3, 4, 5, 6, 7] |
| 229 | >>> random.shuffle(items) |
| 230 | >>> items |
| 231 | [7, 3, 2, 5, 6, 4, 1] |
| 232 | |
| 233 | >>> random.sample([1, 2, 3, 4, 5], 3) # Choose 3 elements |
| 234 | [4, 1, 5] |
| 235 | |
| 236 | |
| 237 | |
| 238 | .. seealso:: |
| 239 | |
| 240 | M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally |
| 241 | equidistributed uniform pseudorandom number generator", ACM Transactions on |
| 242 | Modeling and Computer Simulation Vol. 8, No. 1, January pp.3-30 1998. |
| 243 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 244 | |