mirror of https://github.com/python/cpython
277 lines
11 KiB
TeX
277 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, a function to
|
|
generate a random permutation of a list in-place, and a function for
|
|
random sampling without replacement.
|
|
|
|
On the real line, there are functions to compute uniform, normal (Gaussian),
|
|
lognormal, negative exponential, gamma, and beta distributions.
|
|
For generating distributions of angles, the von Mises distribution
|
|
is 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 Mersenne Twister as
|
|
the core generator. It produces 53-bit precision floats and has a
|
|
period of 2**19937-1. The underlying implementation in C
|
|
is both fast and threadsafe. The Mersenne Twister is one of the most
|
|
extensively tested random number generators in existence. However, being
|
|
completely deterministic, it is not suitable for all purposes, and is
|
|
completely unsuitable for cryptographic purposes.
|
|
|
|
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.
|
|
|
|
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.
|
|
Optionally, a new generator can supply a \method{getrandombits()}
|
|
method --- this allows \method{randrange()} to produce selections
|
|
over an arbitrarily large range.
|
|
\versionadded[the \method{getrandombits()} method]{2.4}
|
|
|
|
As an example of subclassing, the \module{random} module provides
|
|
the \class{WichmannHill} class which implements an alternative generator
|
|
in pure Python. The class provides a backward compatible way to
|
|
reproduce results from earlier versions of Python which used the
|
|
Wichmann-Hill algorithm as the core generator.
|
|
\versionchanged[Substituted MersenneTwister for Wichmann-Hill]{2.3}
|
|
|
|
|
|
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 randomness sources are provided by the
|
|
operating system, they are used instead of the system time (see the
|
|
\function{os.urandom()}
|
|
function for details on availability). \versionchanged[formerly,
|
|
operating system resources were not used]{2.4}
|
|
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.
|
|
\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 one different from and likely far away from
|
|
the current state. \var{n} is a non-negative integer which is used to
|
|
scramble the current state vector. 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 far apart.
|
|
\versionadded{2.1}
|
|
\versionchanged[Instead of jumping to a specific state, \var{n} steps
|
|
ahead, \method{jumpahead(\var{n})} jumps to another state likely to be
|
|
separated by many steps.]{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getrandbits}{k}
|
|
Returns a python \class{long} int with \var{k} random bits.
|
|
This method is supplied with the MersenneTwister generator and some
|
|
other generators may also provide it as an optional part of the API.
|
|
When available, \method{getrandbits()} enables \method{randrange()}
|
|
to handle arbitrarily large ranges.
|
|
\versionadded{2.4}
|
|
\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}.
|
|
If \var{seq} is empty, raises \exception{IndexError}.
|
|
\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.
|
|
\versionadded{2.3}
|
|
|
|
Returns a new list containing elements from the population while
|
|
leaving the original population unchanged. The resulting list is
|
|
in selection order so that all sub-slices will also be valid random
|
|
samples. This allows raffle winners (the sample) to be partitioned
|
|
into grand prize and second place winners (the subslices).
|
|
|
|
Members of the population need not be hashable or unique. If the
|
|
population contains repeats, then each occurrence is a possible
|
|
selection in the sample.
|
|
|
|
To choose a sample from a range of integers, use an \function{xrange()}
|
|
object as an argument. This is especially fast and space efficient for
|
|
sampling from a large population: \code{sample(xrange(10000000), 60)}.
|
|
\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}{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}
|
|
|
|
Alternative Generators
|
|
|
|
\begin{classdesc}{WichmannHill}{\optional{seed}}
|
|
Class that implements the Wichmann-Hill algorithm as the core generator.
|
|
Has all of the same methods as \class{Random} plus the \method{whseed()}
|
|
method described below. Because this class is implemented in pure
|
|
Python, it is not threadsafe and may require locks between calls. The
|
|
period of the generator is 6,953,607,871,644 which is small enough to
|
|
require care that two independent random sequences do not overlap.
|
|
\end{classdesc}
|
|
|
|
\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{classdesc}{SystemRandom}{\optional{seed}}
|
|
Class that uses the \function{os.urandom()} function for generating
|
|
random numbers from sources provided by the operating system.
|
|
Not available on all systems.
|
|
Does not rely on software state and sequences are not reproducible.
|
|
Accordingly, the \method{seed()} and \method{jumpahead()} methods
|
|
have no effect and are ignored. The \method{getstate()} and
|
|
\method{setstate()} methods raise \exception{NotImplementedError} if
|
|
called.
|
|
\versionadded{2.4}
|
|
\end{classdesc}
|
|
|
|
\begin{seealso}
|
|
\seetext{M. Matsumoto and T. Nishimura, ``Mersenne Twister: A
|
|
623-dimensionally equidistributed uniform pseudorandom
|
|
number generator'',
|
|
\citetitle{ACM Transactions on Modeling and Computer Simulation}
|
|
Vol. 8, No. 1, January pp.3-30 1998.}
|
|
|
|
\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}
|