rest25/library/random.rst => rest262/library/random.rst
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
n13-of a random element, a function to generate a random permutation of a list in-
n13+of a random element, a function to generate a random permutation of a list
14-place, and a function for random sampling without replacement.
14+in-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
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.
n39-Optionally, a new generator can supply a :meth:`getrandombits` method --- this
n39+Optionally, 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
n43-   the :meth:`getrandombits` method.
n43+   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
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
n63-   hashable object. If *x* is omitted or ``None``, current system time is used;
n63+   :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
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
n83+   .. versionchanged:: 2.6
84+      State values produced in Python 2.6 cannot be loaded into earlier versions.
85+ 
83
84.. function:: setstate(state)
85
86   *state* should have been obtained from a previous call to :func:`getstate`, and
87   :func:`setstate` restores the internal state of the generator to what it was at
88   the time :func:`setstate` was called.
89
90   .. versionadded:: 2.1
91
92
93.. function:: jumpahead(n)
94
95   Change the internal state to one different from and likely far away from the
96   current state.  *n* is a non-negative integer which is used to scramble the
97   current state vector.  This is most useful in multi-threaded programs, in
n98-   conjuction with multiple instances of the :class:`Random` class:
n101+   conjunction with multiple instances of the :class:`Random` class:
99   :meth:`setstate` or :meth:`seed` can be used to force all instances into the
100   same internal state, and then :meth:`jumpahead` can be used to force the
101   instances' states far apart.
102
103   .. versionadded:: 2.1
104
105   .. versionchanged:: 2.3
n106-      Instead of jumping to a specific state, *n* steps ahead, :meth:`jumpahead(n)`
n109+      Instead of jumping to a specific state, *n* steps ahead, ``jumpahead(n)``
107      jumps to another state likely to be separated by many steps.
108
109
110.. function:: getrandbits(k)
111
112   Returns a python :class:`long` int with *k* random bits. This method is supplied
113   with the MersenneTwister generator and some other generators may also provide it
114   as an optional part of the API. When available, :meth:`getrandbits` enables
160   .. versionadded:: 2.3
161
162   Returns a new list containing elements from the population while leaving the
163   original population unchanged.  The resulting list is in selection order so that
164   all sub-slices will also be valid random samples.  This allows raffle winners
165   (the sample) to be partitioned into grand prize and second place winners (the
166   subslices).
167
n168-   Members of the population need not be hashable or unique.  If the population
n171+   Members of the population need not be :term:`hashable` or unique.  If the population
169   contains repeats, then each occurrence is a possible selection in the sample.
170
171   To choose a sample from a range of integers, use an :func:`xrange` object as an
172   argument.  This is especially fast and space efficient for sampling from a large
173   population:  ``sample(xrange(10000000), 60)``.
174
175The following functions generate specific real-valued distributions. Function
176parameters are named after the corresponding variables in the distribution's
180
181.. function:: random()
182
183   Return the next random floating point number in the range [0.0, 1.0).
184
185
186.. function:: uniform(a, b)
187
n188-   Return a random real number *N* such that ``a <= N < b``.
n191+   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+ 
195+.. function:: triangular(low, high, mode)
196+ 
197+   Return a random floating point number *N* such that ``low <= N <= high`` and
198+   with the specified *mode* between those bounds.  The *low* and *high* bounds
199+   default to zero and one.  The *mode* argument defaults to the midpoint
200+   between the bounds, giving a symmetric distribution.
201+ 
202+   .. versionadded:: 2.6
189
190
191.. function:: betavariate(alpha, beta)
192
n193-   Beta distribution.  Conditions on the parameters are ``alpha > -1`` and ``beta >
n207+   Beta distribution.  Conditions on the parameters are ``alpha > 0`` and
194-   -1``. Returned values range between 0 and 1.
208+   ``beta > 0``. Returned values range between 0 and 1.
195
196
197.. function:: expovariate(lambd)
198
n199-   Exponential distribution.  *lambd* is 1.0 divided by the desired mean.  (The
n213+   Exponential distribution.  *lambd* is 1.0 divided by the desired
200-   parameter would be called "lambda", but that is a reserved word in Python.)
214+   mean.  It should be nonzero.  (The parameter would be called
201-   Returned values range from 0 to positive infinity.
215+   "lambda", but that is a reserved word in Python.)  Returned values
216+   range from 0 to positive infinity if *lambd* is positive, and from
217+   negative infinity to 0 if *lambd* is negative.
202
203
204.. function:: gammavariate(alpha, beta)
205
n206-   Gamma distribution.  (*Not* the gamma function!)  Conditions on the parameters
n222+   Gamma distribution.  (*Not* the gamma function!)  Conditions on the
207-   are ``alpha > 0`` and ``beta > 0``.
223+   parameters are ``alpha > 0`` and ``beta > 0``.
208
209
210.. function:: gauss(mu, sigma)
211
n212-   Gaussian distribution.  *mu* is the mean, and *sigma* is the standard deviation.
n228+   Gaussian distribution.  *mu* is the mean, and *sigma* is the standard
213-   This is slightly faster than the :func:`normalvariate` function defined below.
229+   deviation.  This is slightly faster than the :func:`normalvariate` function
230+   defined below.
214
215
216.. function:: lognormvariate(mu, sigma)
217
218   Log normal distribution.  If you take the natural logarithm of this
219   distribution, you'll get a normal distribution with mean *mu* and standard
220   deviation *sigma*.  *mu* can have any value, and *sigma* must be greater than
221   zero.
223
224.. function:: normalvariate(mu, sigma)
225
226   Normal distribution.  *mu* is the mean, and *sigma* is the standard deviation.
227
228
229.. function:: vonmisesvariate(mu, kappa)
230
n231-   *mu* is the mean angle, expressed in radians between 0 and 2\**pi*, and *kappa*
n248+   *mu* is the mean angle, expressed in radians between 0 and 2\**pi*, and *kappa*
232   is the concentration parameter, which must be greater than or equal to zero.  If
233   *kappa* is equal to zero, this distribution reduces to a uniform random angle
n234-   over the range 0 to 2\**pi*.
n251+   over the range 0 to 2\**pi*.
235
236
237.. function:: paretovariate(alpha)
238
239   Pareto distribution.  *alpha* is the shape parameter.
240
241
242.. function:: weibullvariate(alpha, beta)
243
244   Weibull distribution.  *alpha* is the scale parameter and *beta* is the shape
245   parameter.
246
n264+ 
247Alternative Generators:
n248- 
249
250.. class:: WichmannHill([seed])
251
252   Class that implements the Wichmann-Hill algorithm as the core generator. Has all
253   of the same methods as :class:`Random` plus the :meth:`whseed` method described
254   below.  Because this class is implemented in pure Python, it is not threadsafe
255   and may require locks between calls.  The period of the generator is
256   6,953,607,871,644 which is small enough to require care that two independent
303
304   M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally
305   equidistributed uniform pseudorandom number generator", ACM Transactions on
306   Modeling and Computer Simulation Vol. 8, No. 1, January pp.3-30 1998.
307
308   Wichmann, B. A. & Hill, I. D., "Algorithm AS 183: An efficient and portable
309   pseudo-random number generator", Applied Statistics 31 (1982) 188-190.
310
t311-   http://www.npl.co.uk/ssfm/download/abstracts.html#196
t328+   `Complementary-Multiply-with-Carry recipe
312-      A modern variation of the Wichmann-Hill generator that greatly increases the
329+   <http://code.activestate.com/recipes/576707/>`_ for a compatible alternative
313-      period, and passes now-standard statistical tests that the original generator
330+   random number generator with a long period and comparatively simple update
314-      failed.
331+   operations.
315- 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op