mirror of
https://github.com/python/cpython.git
synced 2025-11-03 23:21:29 +00:00
286 lines
11 KiB
TeX
286 lines
11 KiB
TeX
\section{\module{random} ---
|
|
Generate pseudo-random numbers}
|
|
|
|
\declaremodule{standard}{random}
|
|
\modulesynopsis{Generate pseudo-random numbers with various common
|
|
distributions.}
|
|
|
|
|
|
This module implements pseudo-random number generators for various
|
|
distributions.
|
|
For integers, uniform selection from a range.
|
|
For sequences, uniform selection of a random element, and a function to
|
|
generate a random permutation of a list in-place.
|
|
On the real line, there are functions to compute uniform, normal (Gaussian),
|
|
lognormal, negative exponential, gamma, and beta distributions.
|
|
For generating distribution of angles, the circular uniform and
|
|
von Mises distributions are available.
|
|
|
|
Almost all module functions depend on the basic function
|
|
\function{random()}, which generates a random float uniformly in
|
|
the semi-open range [0.0, 1.0). Python uses the standard Wichmann-Hill
|
|
generator, combining three pure multiplicative congruential
|
|
generators of modulus 30269, 30307 and 30323. Its period (how many
|
|
numbers it generates before repeating the sequence exactly) is
|
|
6,953,607,871,644. While of much higher quality than the \function{rand()}
|
|
function supplied by most C libraries, the theoretical properties
|
|
are much the same as for a single linear congruential generator of
|
|
large modulus. It is not suitable for all purposes, and is completely
|
|
unsuitable for cryptographic purposes.
|
|
|
|
The functions in this module are not threadsafe: if you want to call these
|
|
functions from multiple threads, you should explicitly serialize the calls.
|
|
Else, because no critical sections are implemented internally, calls
|
|
from different threads may see the same return values.
|
|
|
|
The functions supplied by this module are actually bound methods of a
|
|
hidden instance of the \class{random.Random} class. You can
|
|
instantiate your own instances of \class{Random} to get generators
|
|
that don't share state. This is especially useful for multi-threaded
|
|
programs, creating a different instance of \class{Random} for each
|
|
thread, and using the \method{jumpahead()} method to ensure that the
|
|
generated sequences seen by each thread don't overlap (see example
|
|
below).
|
|
|
|
Class \class{Random} can also be subclassed if you want to use a
|
|
different basic generator of your own devising: in that case, override
|
|
the \method{random()}, \method{seed()}, \method{getstate()},
|
|
\method{setstate()} and \method{jumpahead()} methods.
|
|
|
|
Here's one way to create threadsafe distinct and non-overlapping generators:
|
|
|
|
\begin{verbatim}
|
|
def create_generators(num, delta, firstseed=None):
|
|
"""Return list of num distinct generators.
|
|
Each generator has its own unique segment of delta elements
|
|
from Random.random()'s full period.
|
|
Seed the first generator with optional arg firstseed (default
|
|
is None, to seed from current time).
|
|
"""
|
|
|
|
from random import Random
|
|
g = Random(firstseed)
|
|
result = [g]
|
|
for i in range(num - 1):
|
|
laststate = g.getstate()
|
|
g = Random()
|
|
g.setstate(laststate)
|
|
g.jumpahead(delta)
|
|
result.append(g)
|
|
return result
|
|
|
|
gens = create_generators(10, 1000000)
|
|
\end{verbatim}
|
|
|
|
That creates 10 distinct generators, which can be passed out to 10
|
|
distinct threads. The generators don't share state so can be called
|
|
safely in parallel. So long as no thread calls its \code{g.random()}
|
|
more than a million times (the second argument to
|
|
\function{create_generators()}, the sequences seen by each thread will
|
|
not overlap. The period of the underlying Wichmann-Hill generator
|
|
limits how far this technique can be pushed.
|
|
|
|
Just for fun, note that since we know the period, \method{jumpahead()}
|
|
can also be used to ``move backward in time:''
|
|
|
|
\begin{verbatim}
|
|
>>> g = Random(42) # arbitrary
|
|
>>> g.random()
|
|
0.25420336316883324
|
|
>>> g.jumpahead(6953607871644L - 1) # move *back* one
|
|
>>> g.random()
|
|
0.25420336316883324
|
|
\end{verbatim}
|
|
|
|
|
|
Bookkeeping functions:
|
|
|
|
\begin{funcdesc}{seed}{\optional{x}}
|
|
Initialize the basic random number generator.
|
|
Optional argument \var{x} can be any hashable object.
|
|
If \var{x} is omitted or \code{None}, current system time is used;
|
|
current system time is also used to initialize the generator when the
|
|
module is first imported.
|
|
If \var{x} is not \code{None} or an int or long,
|
|
\code{hash(\var{x})} is used instead.
|
|
If \var{x} is an int or long, \var{x} is used directly.
|
|
Distinct values between 0 and 27814431486575L inclusive are guaranteed
|
|
to yield distinct internal states (this guarantee is specific to the
|
|
default Wichmann-Hill generator, and may not apply to subclasses
|
|
supplying their own basic generator).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{whseed}{\optional{x}}
|
|
This is obsolete, supplied for bit-level compatibility with versions
|
|
of Python prior to 2.1.
|
|
See \function{seed} for details. \function{whseed} does not guarantee
|
|
that distinct integer arguments yield distinct internal states, and can
|
|
yield no more than about 2**24 distinct internal states in all.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getstate}{}
|
|
Return an object capturing the current internal state of the
|
|
generator. This object can be passed to \function{setstate()} to
|
|
restore the state.
|
|
\versionadded{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setstate}{state}
|
|
\var{state} should have been obtained from a previous call to
|
|
\function{getstate()}, and \function{setstate()} restores the
|
|
internal state of the generator to what it was at the time
|
|
\function{setstate()} was called.
|
|
\versionadded{2.1}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{jumpahead}{n}
|
|
Change the internal state to what it would be if \function{random()}
|
|
were called \var{n} times, but do so quickly. \var{n} is a
|
|
non-negative integer. This is most useful in multi-threaded
|
|
programs, in conjuction with multiple instances of the \class{Random}
|
|
class: \method{setstate()} or \method{seed()} can be used to force
|
|
all instances into the same internal state, and then
|
|
\method{jumpahead()} can be used to force the instances' states as
|
|
far apart as you like (up to the period of the generator).
|
|
\versionadded{2.1}
|
|
\end{funcdesc}
|
|
|
|
Functions for integers:
|
|
|
|
\begin{funcdesc}{randrange}{\optional{start,} stop\optional{, step}}
|
|
Return a randomly selected element from \code{range(\var{start},
|
|
\var{stop}, \var{step})}. This is equivalent to
|
|
\code{choice(range(\var{start}, \var{stop}, \var{step}))},
|
|
but doesn't actually build a range object.
|
|
\versionadded{1.5.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{randint}{a, b}
|
|
Return a random integer \var{N} such that
|
|
\code{\var{a} <= \var{N} <= \var{b}}.
|
|
\end{funcdesc}
|
|
|
|
|
|
Functions for sequences:
|
|
|
|
\begin{funcdesc}{choice}{seq}
|
|
Return a random element from the non-empty sequence \var{seq}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{shuffle}{x\optional{, random}}
|
|
Shuffle the sequence \var{x} in place.
|
|
The optional argument \var{random} is a 0-argument function
|
|
returning a random float in [0.0, 1.0); by default, this is the
|
|
function \function{random()}.
|
|
|
|
Note that for even rather small \code{len(\var{x})}, the total
|
|
number of permutations of \var{x} is larger than the period of most
|
|
random number generators; this implies that most permutations of a
|
|
long sequence can never be generated.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sample}{population, k}
|
|
Return a \var{k} length list of unique elements chosen from the
|
|
population sequence. Used for random sampling without replacement.
|
|
|
|
Returns a new list containing elements from the population. The
|
|
list itself is in random order so that all sub-slices are also
|
|
random samples. The original sequence is left undisturbed.
|
|
|
|
If the population has repeated elements, then each occurence is a
|
|
possible selection in the sample.
|
|
|
|
If indices are needed for a large population, use \function{xrange}
|
|
as an argument: \code{sample(xrange(10000000), 60)}.
|
|
|
|
Optional argument random is a 0-argument function returning a random
|
|
float in [0.0, 1.0); by default, the standard random.random.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
|
|
The following functions generate specific real-valued distributions.
|
|
Function parameters are named after the corresponding variables in the
|
|
distribution's equation, as used in common mathematical practice; most of
|
|
these equations can be found in any statistics text.
|
|
|
|
\begin{funcdesc}{random}{}
|
|
Return the next random floating point number in the range [0.0, 1.0).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{uniform}{a, b}
|
|
Return a random real number \var{N} such that
|
|
\code{\var{a} <= \var{N} < \var{b}}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{betavariate}{alpha, beta}
|
|
Beta distribution. Conditions on the parameters are
|
|
\code{\var{alpha} > -1} and \code{\var{beta} > -1}.
|
|
Returned values range between 0 and 1.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{cunifvariate}{mean, arc}
|
|
Circular uniform distribution. \var{mean} is the mean angle, and
|
|
\var{arc} is the range of the distribution, centered around the mean
|
|
angle. Both values must be expressed in radians, and can range
|
|
between 0 and \emph{pi}. Returned values range between
|
|
\code{\var{mean} - \var{arc}/2} and \code{\var{mean} +
|
|
\var{arc}/2} and are normalized to between 0 and \emph{pi}.
|
|
|
|
\deprecated{2.3}{Instead, use \code{(\var{mean} + \var{arc} *
|
|
(random.random() - 0.5)) \% math.pi}.}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{expovariate}{lambd}
|
|
Exponential distribution. \var{lambd} is 1.0 divided by the desired
|
|
mean. (The parameter would be called ``lambda'', but that is a
|
|
reserved word in Python.) Returned values range from 0 to
|
|
positive infinity.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{gammavariate}{alpha, beta}
|
|
Gamma distribution. (\emph{Not} the gamma function!) Conditions on
|
|
the parameters are \code{\var{alpha} > 0} and \code{\var{beta} > 0}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{gauss}{mu, sigma}
|
|
Gaussian distribution. \var{mu} is the mean, and \var{sigma} is the
|
|
standard deviation. This is slightly faster than the
|
|
\function{normalvariate()} function defined below.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lognormvariate}{mu, sigma}
|
|
Log normal distribution. If you take the natural logarithm of this
|
|
distribution, you'll get a normal distribution with mean \var{mu}
|
|
and standard deviation \var{sigma}. \var{mu} can have any value,
|
|
and \var{sigma} must be greater than zero.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{normalvariate}{mu, sigma}
|
|
Normal distribution. \var{mu} is the mean, and \var{sigma} is the
|
|
standard deviation.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{vonmisesvariate}{mu, kappa}
|
|
\var{mu} is the mean angle, expressed in radians between 0 and
|
|
2*\emph{pi}, and \var{kappa} is the concentration parameter, which
|
|
must be greater than or equal to zero. If \var{kappa} is equal to
|
|
zero, this distribution reduces to a uniform random angle over the
|
|
range 0 to 2*\emph{pi}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{paretovariate}{alpha}
|
|
Pareto distribution. \var{alpha} is the shape parameter.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{weibullvariate}{alpha, beta}
|
|
Weibull distribution. \var{alpha} is the scale parameter and
|
|
\var{beta} is the shape parameter.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183:
|
|
An efficient and portable pseudo-random number generator'',
|
|
\citetitle{Applied Statistics} 31 (1982) 188-190.}
|
|
\end{seealso}
|