diff options
Diffstat (limited to 'Doc/lib/librandom.tex')
| -rw-r--r-- | Doc/lib/librandom.tex | 309 |
1 files changed, 0 insertions, 309 deletions
diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex deleted file mode 100644 index a9bd5ac..0000000 --- a/Doc/lib/librandom.tex +++ /dev/null @@ -1,309 +0,0 @@ -\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 make it likely 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 that 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. Note that this Wichmann-Hill -generator can no longer be recommended: its period is too short by -contemporary standards, and the sequence generated is known to fail some -stringent randomness tests. See the references below for a recent -variant that repairs these flaws. -\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{range()} - object as an argument. This is especially fast and space efficient for - sampling from a large population: \code{sample(range(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} > 0} and \code{\var{beta} > 0}. - 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} - -Examples of basic usage: - -\begin{verbatim} ->>> random.random() # Random float x, 0.0 <= x < 1.0 -0.37444887175646646 ->>> random.uniform(1, 10) # Random float x, 1.0 <= x < 10.0 -1.1800146073117523 ->>> random.randint(1, 10) # Integer from 1 to 10, endpoints included -7 ->>> random.randrange(0, 101, 2) # Even integer from 0 to 100 -26 ->>> random.choice('abcdefghij') # Choose a random element -'c' - ->>> items = [1, 2, 3, 4, 5, 6, 7] ->>> random.shuffle(items) ->>> items -[7, 3, 2, 5, 6, 4, 1] - ->>> random.sample([1, 2, 3, 4, 5], 3) # Choose 3 elements -[4, 1, 5] - -\end{verbatim} - -\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.} - - \seeurl{http://www.npl.co.uk/ssfm/download/abstracts.html\#196}{A modern - variation of the Wichmann-Hill generator that greatly increases - the period, and passes now-standard statistical tests that the - original generator failed.} -\end{seealso} |