← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/library/random.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
 
 
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
 
31
instances of :class:`Random` to get generators that don't share state.
 
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`,
 
35
:meth:`seed`, :meth:`getstate`, and :meth:`setstate` methods.
 
36
Optionally, a new generator can supply a :meth:`getrandbits` method --- this
 
37
allows :meth:`randrange` to produce selections over an arbitrarily large range.
 
38
 
 
39
 
 
40
Bookkeeping functions:
 
41
 
 
42
 
 
43
.. function:: seed([x])
 
44
 
 
45
   Initialize the basic random number generator. Optional argument *x* can be any
 
46
   :term:`hashable` object. If *x* is omitted or ``None``, current system time is used;
 
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
 
 
52
   If *x* is not ``None`` or an int, ``hash(x)`` is used instead. If *x* is an
 
53
   int, *x* is used directly.
 
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
 
 
61
 
 
62
.. function:: setstate(state)
 
63
 
 
64
   *state* should have been obtained from a previous call to :func:`getstate`, and
 
65
   :func:`setstate` restores the internal state of the generator to what it was at
 
66
   the time :func:`setstate` was called.
 
67
 
 
68
 
 
69
.. function:: getrandbits(k)
 
70
 
 
71
   Returns a python integer with *k* random bits. This method is supplied with
 
72
   the MersenneTwister generator and some other generators may also provide it
 
73
   as an optional part of the API. When available, :meth:`getrandbits` enables
 
74
   :meth:`randrange` to handle arbitrarily large ranges.
 
75
 
 
76
 
 
77
Functions for integers:
 
78
 
 
79
.. function:: randrange([start,] stop[, step])
 
80
 
 
81
   Return a randomly selected element from ``range(start, stop, step)``.  This is
 
82
   equivalent to ``choice(range(start, stop, step))``, but doesn't actually build a
 
83
   range object.
 
84
 
 
85
 
 
86
.. function:: randint(a, b)
 
87
 
 
88
   Return a random integer *N* such that ``a <= N <= b``.  Alias for
 
89
   ``randrange(a, b+1)``.
 
90
 
 
91
 
 
92
Functions for sequences:
 
93
 
 
94
.. function:: choice(seq)
 
95
 
 
96
   Return a random element from the non-empty sequence *seq*. If *seq* is empty,
 
97
   raises :exc:`IndexError`.
 
98
 
 
99
 
 
100
.. function:: shuffle(x[, random])
 
101
 
 
102
   Shuffle the sequence *x* in place. The optional argument *random* is a
 
103
   0-argument function returning a random float in [0.0, 1.0); by default, this is
 
104
   the function :func:`random`.
 
105
 
 
106
   Note that for even rather small ``len(x)``, the total number of permutations of
 
107
   *x* is larger than the period of most random number generators; this implies
 
108
   that most permutations of a long sequence can never be generated.
 
109
 
 
110
 
 
111
.. function:: sample(population, k)
 
112
 
 
113
   Return a *k* length list of unique elements chosen from the population sequence
 
114
   or set. Used for random sampling without replacement.
 
115
 
 
116
   Returns a new list containing elements from the population while leaving the
 
117
   original population unchanged.  The resulting list is in selection order so that
 
118
   all sub-slices will also be valid random samples.  This allows raffle winners
 
119
   (the sample) to be partitioned into grand prize and second place winners (the
 
120
   subslices).
 
121
 
 
122
   Members of the population need not be :term:`hashable` or unique.  If the population
 
123
   contains repeats, then each occurrence is a possible selection in the sample.
 
124
 
 
125
   To choose a sample from a range of integers, use an :func:`range` object as an
 
126
   argument.  This is especially fast and space efficient for sampling from a large
 
127
   population:  ``sample(range(10000000), 60)``.
 
128
 
 
129
The following functions generate specific real-valued distributions. Function
 
130
parameters are named after the corresponding variables in the distribution's
 
131
equation, as used in common mathematical practice; most of these equations can
 
132
be found in any statistics text.
 
133
 
 
134
 
 
135
.. function:: random()
 
136
 
 
137
   Return the next random floating point number in the range [0.0, 1.0).
 
138
 
 
139
 
 
140
.. function:: uniform(a, b)
 
141
 
 
142
   Return a random floating point number *N* such that ``a <= N <= b`` for
 
143
   ``a <= b`` and ``b <= N <= a`` for ``b < a``.
 
144
 
 
145
 
 
146
.. function:: triangular(low, high, mode)
 
147
 
 
148
   Return a random floating point number *N* such that ``low <= N <= high`` and
 
149
   with the specified *mode* between those bounds.  The *low* and *high* bounds
 
150
   default to zero and one.  The *mode* argument defaults to the midpoint
 
151
   between the bounds, giving a symmetric distribution.
 
152
 
 
153
 
 
154
.. function:: betavariate(alpha, beta)
 
155
 
 
156
   Beta distribution.  Conditions on the parameters are ``alpha > 0`` and
 
157
   ``beta > 0``. Returned values range between 0 and 1.
 
158
 
 
159
 
 
160
.. function:: expovariate(lambd)
 
161
 
 
162
   Exponential distribution.  *lambd* is 1.0 divided by the desired
 
163
   mean.  It should be nonzero.  (The parameter would be called
 
164
   "lambda", but that is a reserved word in Python.)  Returned values
 
165
   range from 0 to positive infinity if *lambd* is positive, and from
 
166
   negative infinity to 0 if *lambd* is negative.
 
167
 
 
168
 
 
169
.. function:: gammavariate(alpha, beta)
 
170
 
 
171
   Gamma distribution.  (*Not* the gamma function!)  Conditions on the
 
172
   parameters are ``alpha > 0`` and ``beta > 0``.
 
173
 
 
174
 
 
175
.. function:: gauss(mu, sigma)
 
176
 
 
177
   Gaussian distribution.  *mu* is the mean, and *sigma* is the standard
 
178
   deviation.  This is slightly faster than the :func:`normalvariate` function
 
179
   defined below.
 
180
 
 
181
 
 
182
.. function:: lognormvariate(mu, sigma)
 
183
 
 
184
   Log normal distribution.  If you take the natural logarithm of this
 
185
   distribution, you'll get a normal distribution with mean *mu* and standard
 
186
   deviation *sigma*.  *mu* can have any value, and *sigma* must be greater than
 
187
   zero.
 
188
 
 
189
 
 
190
.. function:: normalvariate(mu, sigma)
 
191
 
 
192
   Normal distribution.  *mu* is the mean, and *sigma* is the standard deviation.
 
193
 
 
194
 
 
195
.. function:: vonmisesvariate(mu, kappa)
 
196
 
 
197
   *mu* is the mean angle, expressed in radians between 0 and 2\*\ *pi*, and *kappa*
 
198
   is the concentration parameter, which must be greater than or equal to zero.  If
 
199
   *kappa* is equal to zero, this distribution reduces to a uniform random angle
 
200
   over the range 0 to 2\*\ *pi*.
 
201
 
 
202
 
 
203
.. function:: paretovariate(alpha)
 
204
 
 
205
   Pareto distribution.  *alpha* is the shape parameter.
 
206
 
 
207
 
 
208
.. function:: weibullvariate(alpha, beta)
 
209
 
 
210
   Weibull distribution.  *alpha* is the scale parameter and *beta* is the shape
 
211
   parameter.
 
212
 
 
213
 
 
214
Alternative Generators:
 
215
 
 
216
.. class:: SystemRandom([seed])
 
217
 
 
218
   Class that uses the :func:`os.urandom` function for generating random numbers
 
219
   from sources provided by the operating system. Not available on all systems.
 
220
   Does not rely on software state and sequences are not reproducible. Accordingly,
 
221
   the :meth:`seed` method has no effect and is ignored.
 
222
   The :meth:`getstate` and :meth:`setstate` methods raise
 
223
   :exc:`NotImplementedError` if called.
 
224
 
 
225
 
 
226
Examples of basic usage::
 
227
 
 
228
   >>> random.random()        # Random float x, 0.0 <= x < 1.0
 
229
   0.37444887175646646
 
230
   >>> random.uniform(1, 10)  # Random float x, 1.0 <= x < 10.0
 
231
   1.1800146073117523
 
232
   >>> random.randint(1, 10)  # Integer from 1 to 10, endpoints included
 
233
   7
 
234
   >>> random.randrange(0, 101, 2)  # Even integer from 0 to 100
 
235
   26
 
236
   >>> random.choice('abcdefghij')  # Choose a random element
 
237
   'c'
 
238
 
 
239
   >>> items = [1, 2, 3, 4, 5, 6, 7]
 
240
   >>> random.shuffle(items)
 
241
   >>> items
 
242
   [7, 3, 2, 5, 6, 4, 1]
 
243
 
 
244
   >>> random.sample([1, 2, 3, 4, 5],  3)  # Choose 3 elements
 
245
   [4, 1, 5]
 
246
 
 
247
 
 
248
 
 
249
.. seealso::
 
250
 
 
251
   M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally
 
252
   equidistributed uniform pseudorandom number generator", ACM Transactions on
 
253
   Modeling and Computer Simulation Vol. 8, No. 1, January pp.3-30 1998.
 
254
 
 
255