/Doc/library/random.rst

  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
  9This module implements pseudo-random number generators for various
 10distributions.
 11
 12For integers, uniform selection from a range. For sequences, uniform selection
 13of a random element, a function to generate a random permutation of a list
 14in-place, and a function for random sampling without replacement.
 15
 16On the real line, there are functions to compute uniform, normal (Gaussian),
 17lognormal, negative exponential, gamma, and beta distributions. For generating
 18distributions of angles, the von Mises distribution is available.
 19
 20Almost all module functions depend on the basic function :func:`random`, which
 21generates a random float uniformly in the semi-open range [0.0, 1.0).  Python
 22uses the Mersenne Twister as the core generator.  It produces 53-bit precision
 23floats and has a period of 2\*\*19937-1.  The underlying implementation in C is
 24both fast and threadsafe.  The Mersenne Twister is one of the most extensively
 25tested random number generators in existence.  However, being completely
 26deterministic, it is not suitable for all purposes, and is completely unsuitable
 27for cryptographic purposes.
 28
 29The functions supplied by this module are actually bound methods of a hidden
 30instance of the :class:`random.Random` class.  You can instantiate your own
 31instances of :class:`Random` to get generators that don't share state.  This is
 32especially useful for multi-threaded programs, creating a different instance of
 33:class:`Random` for each thread, and using the :meth:`jumpahead` method to make
 34it likely that the generated sequences seen by each thread don't overlap.
 35
 36Class :class:`Random` can also be subclassed if you want to use a different
 37basic generator of your own devising: in that case, override the :meth:`random`,
 38:meth:`seed`, :meth:`getstate`, :meth:`setstate` and :meth:`jumpahead` methods.
 39Optionally, a new generator can supply a :meth:`getrandbits` method --- this
 40allows :meth:`randrange` to produce selections over an arbitrarily large range.
 41
 42.. versionadded:: 2.4
 43   the :meth:`getrandbits` method.
 44
 45As an example of subclassing, the :mod:`random` module provides the
 46:class:`WichmannHill` class that implements an alternative generator in pure
 47Python.  The class provides a backward compatible way to reproduce results from
 48earlier versions of Python, which used the Wichmann-Hill algorithm as the core
 49generator.  Note that this Wichmann-Hill generator can no longer be recommended:
 50its period is too short by contemporary standards, and the sequence generated is
 51known to fail some stringent randomness tests.  See the references below for a
 52recent variant that repairs these flaws.
 53
 54.. versionchanged:: 2.3
 55   Substituted MersenneTwister for Wichmann-Hill.
 56
 57Bookkeeping functions:
 58
 59
 60.. function:: seed([x])
 61
 62   Initialize the basic random number generator. Optional argument *x* can be any
 63   :term:`hashable` object. If *x* is omitted or ``None``, current system time is used;
 64   current system time is also used to initialize the generator when the module is
 65   first imported.  If randomness sources are provided by the operating system,
 66   they are used instead of the system time (see the :func:`os.urandom` function
 67   for details on availability).
 68
 69   .. versionchanged:: 2.4
 70      formerly, operating system resources were not used.
 71
 72   If *x* is not ``None`` or an int or long, ``hash(x)`` is used instead. If *x* is
 73   an int or long, *x* is used directly.
 74
 75
 76.. function:: getstate()
 77
 78   Return an object capturing the current internal state of the generator.  This
 79   object can be passed to :func:`setstate` to restore the state.
 80
 81   .. versionadded:: 2.1
 82
 83   .. versionchanged:: 2.6
 84      State values produced in Python 2.6 cannot be loaded into earlier versions.
 85
 86
 87.. function:: setstate(state)
 88
 89   *state* should have been obtained from a previous call to :func:`getstate`, and
 90   :func:`setstate` restores the internal state of the generator to what it was at
 91   the time :func:`setstate` was called.
 92
 93   .. versionadded:: 2.1
 94
 95
 96.. function:: jumpahead(n)
 97
 98   Change the internal state to one different from and likely far away from the
 99   current state.  *n* is a non-negative integer which is used to scramble the
100   current state vector.  This is most useful in multi-threaded programs, in
101   conjunction with multiple instances of the :class:`Random` class:
102   :meth:`setstate` or :meth:`seed` can be used to force all instances into the
103   same internal state, and then :meth:`jumpahead` can be used to force the
104   instances' states far apart.
105
106   .. versionadded:: 2.1
107
108   .. versionchanged:: 2.3
109      Instead of jumping to a specific state, *n* steps ahead, ``jumpahead(n)``
110      jumps to another state likely to be separated by many steps.
111
112
113.. function:: getrandbits(k)
114
115   Returns a python :class:`long` int with *k* random bits. This method is supplied
116   with the MersenneTwister generator and some other generators may also provide it
117   as an optional part of the API. When available, :meth:`getrandbits` enables
118   :meth:`randrange` to handle arbitrarily large ranges.
119
120   .. versionadded:: 2.4
121
122Functions for integers:
123
124
125.. function:: randrange([start,] stop[, step])
126
127   Return a randomly selected element from ``range(start, stop, step)``.  This is
128   equivalent to ``choice(range(start, stop, step))``, but doesn't actually build a
129   range object.
130
131   .. versionadded:: 1.5.2
132
133
134.. function:: randint(a, b)
135
136   Return a random integer *N* such that ``a <= N <= b``.
137
138Functions for sequences:
139
140
141.. function:: choice(seq)
142
143   Return a random element from the non-empty sequence *seq*. If *seq* is empty,
144   raises :exc:`IndexError`.
145
146
147.. function:: shuffle(x[, random])
148
149   Shuffle the sequence *x* in place. The optional argument *random* is a
150   0-argument function returning a random float in [0.0, 1.0); by default, this is
151   the function :func:`random`.
152
153   Note that for even rather small ``len(x)``, the total number of permutations of
154   *x* is larger than the period of most random number generators; this implies
155   that most permutations of a long sequence can never be generated.
156
157
158.. function:: sample(population, k)
159
160   Return a *k* length list of unique elements chosen from the population sequence.
161   Used for random sampling without replacement.
162
163   .. versionadded:: 2.3
164
165   Returns a new list containing elements from the population while leaving the
166   original population unchanged.  The resulting list is in selection order so that
167   all sub-slices will also be valid random samples.  This allows raffle winners
168   (the sample) to be partitioned into grand prize and second place winners (the
169   subslices).
170
171   Members of the population need not be :term:`hashable` or unique.  If the population
172   contains repeats, then each occurrence is a possible selection in the sample.
173
174   To choose a sample from a range of integers, use an :func:`xrange` object as an
175   argument.  This is especially fast and space efficient for sampling from a large
176   population:  ``sample(xrange(10000000), 60)``.
177
178The following functions generate specific real-valued distributions. Function
179parameters are named after the corresponding variables in the distribution's
180equation, as used in common mathematical practice; most of these equations can
181be found in any statistics text.
182
183
184.. function:: random()
185
186   Return the next random floating point number in the range [0.0, 1.0).
187
188
189.. function:: uniform(a, b)
190
191   Return a random floating point number *N* such that ``a <= N <= b`` for
192   ``a <= b`` and ``b <= N <= a`` for ``b < a``.
193
194   The end-point value ``b`` may or may not be included in the range
195   depending on floating-point rounding in the equation ``a + (b-a) * random()``.
196
197.. function:: triangular(low, high, mode)
198
199   Return a random floating point number *N* such that ``low <= N <= high`` and
200   with the specified *mode* between those bounds.  The *low* and *high* bounds
201   default to zero and one.  The *mode* argument defaults to the midpoint
202   between the bounds, giving a symmetric distribution.
203
204   .. versionadded:: 2.6
205
206
207.. function:: betavariate(alpha, beta)
208
209   Beta distribution.  Conditions on the parameters are ``alpha > 0`` and
210   ``beta > 0``. Returned values range between 0 and 1.
211
212
213.. function:: expovariate(lambd)
214
215   Exponential distribution.  *lambd* is 1.0 divided by the desired
216   mean.  It should be nonzero.  (The parameter would be called
217   "lambda", but that is a reserved word in Python.)  Returned values
218   range from 0 to positive infinity if *lambd* is positive, and from
219   negative infinity to 0 if *lambd* is negative.
220
221
222.. function:: gammavariate(alpha, beta)
223
224   Gamma distribution.  (*Not* the gamma function!)  Conditions on the
225   parameters are ``alpha > 0`` and ``beta > 0``.
226
227
228.. function:: gauss(mu, sigma)
229
230   Gaussian distribution.  *mu* is the mean, and *sigma* is the standard
231   deviation.  This is slightly faster than the :func:`normalvariate` function
232   defined below.
233
234
235.. function:: lognormvariate(mu, sigma)
236
237   Log normal distribution.  If you take the natural logarithm of this
238   distribution, you'll get a normal distribution with mean *mu* and standard
239   deviation *sigma*.  *mu* can have any value, and *sigma* must be greater than
240   zero.
241
242
243.. function:: normalvariate(mu, sigma)
244
245   Normal distribution.  *mu* is the mean, and *sigma* is the standard deviation.
246
247
248.. function:: vonmisesvariate(mu, kappa)
249
250   *mu* is the mean angle, expressed in radians between 0 and 2\*\ *pi*, and *kappa*
251   is the concentration parameter, which must be greater than or equal to zero.  If
252   *kappa* is equal to zero, this distribution reduces to a uniform random angle
253   over the range 0 to 2\*\ *pi*.
254
255
256.. function:: paretovariate(alpha)
257
258   Pareto distribution.  *alpha* is the shape parameter.
259
260
261.. function:: weibullvariate(alpha, beta)
262
263   Weibull distribution.  *alpha* is the scale parameter and *beta* is the shape
264   parameter.
265
266
267Alternative Generators:
268
269.. class:: WichmannHill([seed])
270
271   Class that implements the Wichmann-Hill algorithm as the core generator. Has all
272   of the same methods as :class:`Random` plus the :meth:`whseed` method described
273   below.  Because this class is implemented in pure Python, it is not threadsafe
274   and may require locks between calls.  The period of the generator is
275   6,953,607,871,644 which is small enough to require care that two independent
276   random sequences do not overlap.
277
278
279.. function:: whseed([x])
280
281   This is obsolete, supplied for bit-level compatibility with versions of Python
282   prior to 2.1. See :func:`seed` for details.  :func:`whseed` does not guarantee
283   that distinct integer arguments yield distinct internal states, and can yield no
284   more than about 2\*\*24 distinct internal states in all.
285
286
287.. class:: SystemRandom([seed])
288
289   Class that uses the :func:`os.urandom` function for generating random numbers
290   from sources provided by the operating system. Not available on all systems.
291   Does not rely on software state and sequences are not reproducible. Accordingly,
292   the :meth:`seed` and :meth:`jumpahead` methods have no effect and are ignored.
293   The :meth:`getstate` and :meth:`setstate` methods raise
294   :exc:`NotImplementedError` if called.
295
296   .. versionadded:: 2.4
297
298Examples of basic usage::
299
300   >>> random.random()        # Random float x, 0.0 <= x < 1.0
301   0.37444887175646646
302   >>> random.uniform(1, 10)  # Random float x, 1.0 <= x < 10.0
303   1.1800146073117523
304   >>> random.randint(1, 10)  # Integer from 1 to 10, endpoints included
305   7
306   >>> random.randrange(0, 101, 2)  # Even integer from 0 to 100
307   26
308   >>> random.choice('abcdefghij')  # Choose a random element
309   'c'
310
311   >>> items = [1, 2, 3, 4, 5, 6, 7]
312   >>> random.shuffle(items)
313   >>> items
314   [7, 3, 2, 5, 6, 4, 1]
315
316   >>> random.sample([1, 2, 3, 4, 5],  3)  # Choose 3 elements
317   [4, 1, 5]
318
319
320
321.. seealso::
322
323   M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally
324   equidistributed uniform pseudorandom number generator", ACM Transactions on
325   Modeling and Computer Simulation Vol. 8, No. 1, January pp.3-30 1998.
326
327   Wichmann, B. A. & Hill, I. D., "Algorithm AS 183: An efficient and portable
328   pseudo-random number generator", Applied Statistics 31 (1982) 188-190.
329
330   `Complementary-Multiply-with-Carry recipe
331   <http://code.activestate.com/recipes/576707/>`_ for a compatible alternative
332   random number generator with a long period and comparatively simple update
333   operations.