From c32f0336e062dd36f82fb236c66ac25e2bac217b Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Thu, 23 May 2002 19:44:49 +0000 Subject: Deprecated Random.cunifvariate clearing bug 506647. Also, added docstrings. --- Doc/lib/librandom.tex | 5 +++- Lib/random.py | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+), 1 deletion(-) diff --git a/Doc/lib/librandom.tex b/Doc/lib/librandom.tex index 3a12ae6..24489bc 100644 --- a/Doc/lib/librandom.tex +++ b/Doc/lib/librandom.tex @@ -206,7 +206,10 @@ these equations can be found in any statistics text. 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}. + \var{arc}/2} and are normalized to between 0 and \emph{pi}. + + \deprecated{2.3}{Instead, use (mean + arc * (Random.random() + - 0.5)) % Math.pi} \end{funcdesc} \begin{funcdesc}{expovariate}{lambd} diff --git a/Lib/random.py b/Lib/random.py index af788c6..424a905 100644 --- a/Lib/random.py +++ b/Lib/random.py @@ -106,6 +106,19 @@ del _verify # Adrian Baddeley. class Random: + """Random number generator base class used by bound module functions. + + Used to instantiate instances of Random to get generators that don't + share state. Especially useful for multi-threaded programs, creating + a different instance of Random for each thread, and using the jumpahead() + method to ensure that the generated sequences seen by each thread don't + overlap. + + Class Random can also be subclassed if you want to use a different basic + generator of your own devising: in that case, override the following + methods: random(), seed(), getstate(), setstate() and jumpahead(). + + """ VERSION = 1 # used by getstate/setstate @@ -358,6 +371,11 @@ class Random: ## -------------------- normal distribution -------------------- def normalvariate(self, mu, sigma): + """Normal distribution. + + mu is the mean, and sigma is the standard deviation. + + """ # mu = mean, sigma = standard deviation # Uses Kinderman and Monahan method. Reference: Kinderman, @@ -378,19 +396,48 @@ class Random: ## -------------------- lognormal distribution -------------------- def lognormvariate(self, mu, sigma): + """Log normal distribution. + + If you take the natural logarithm of this distribution, you'll get a + normal distribution with mean mu and standard deviation sigma. + mu can have any value, and sigma must be greater than zero. + + """ return _exp(self.normalvariate(mu, sigma)) ## -------------------- circular uniform -------------------- def cunifvariate(self, mean, arc): + """Circular uniform distribution. + + mean is the mean angle, and arc is the range of the distribution, + centered around the mean angle. Both values must be expressed in + radians. Returned values range between mean - arc/2 and + mean + arc/2 and are normalized to between 0 and pi. + + Deprecated in version 2.3. Use: + (mean + arc * (Random.random() - 0.5)) % Math.pi + + """ # mean: mean angle (in radians between 0 and pi) # arc: range of distribution (in radians between 0 and pi) + import warnings + warnings.warn("The cunifvariate function is deprecated; Use (mean " + "+ arc * (Random.random() - 0.5)) % Math.pi instead", + DeprecationWarning) return (mean + arc * (self.random() - 0.5)) % _pi ## -------------------- exponential distribution -------------------- def expovariate(self, lambd): + """Exponential distribution. + + 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. + + """ # lambd: rate lambd = 1/mean # ('lambda' is a Python reserved word) @@ -403,6 +450,14 @@ class Random: ## -------------------- von Mises distribution -------------------- def vonmisesvariate(self, mu, kappa): + """Circular data distribution. + + mu is the mean angle, expressed in radians between 0 and 2*pi, and + kappa is the concentration parameter, which must be greater than or + equal to zero. If kappa is equal to zero, this distribution reduces + to a uniform random angle over the range 0 to 2*pi. + + """ # mu: mean angle (in radians between 0 and 2*pi) # kappa: concentration parameter kappa (>= 0) # if kappa = 0 generate uniform random angle @@ -445,6 +500,11 @@ class Random: ## -------------------- gamma distribution -------------------- def gammavariate(self, alpha, beta): + """Gamma distribution. Not the gamma function! + + Conditions on the parameters are alpha > 0 and beta > 0. + + """ # alpha > 0, beta > 0, mean is alpha*beta, variance is alpha*beta**2 @@ -524,6 +584,14 @@ class Random: ## -------------------- Gauss (faster alternative) -------------------- def gauss(self, mu, sigma): + """Gaussian distribution. + + mu is the mean, and sigma is the standard deviation. This is + slightly faster than the normalvariate() function. + + Not thread-safe without a lock around calls. + + """ # When x and y are two variables from [0, 1), uniformly # distributed, then @@ -569,6 +637,13 @@ class Random: ## was dead wrong, and how it probably got that way. def betavariate(self, alpha, beta): + """Beta distribution. + + Conditions on the parameters are alpha > -1 and beta} > -1. + Returned values range between 0 and 1. + + """ + # This version due to Janne Sinkkonen, and matches all the std # texts (e.g., Knuth Vol 2 Ed 3 pg 134 "the beta distribution"). y = self.gammavariate(alpha, 1.) @@ -580,6 +655,7 @@ class Random: ## -------------------- Pareto -------------------- def paretovariate(self, alpha): + """Pareto distribution. alpha is the shape parameter.""" # Jain, pg. 495 u = self.random() @@ -588,6 +664,11 @@ class Random: ## -------------------- Weibull -------------------- def weibullvariate(self, alpha, beta): + """Weibull distribution. + + alpha is the scale parameter and beta is the shape parameter. + + """ # Jain, pg. 499; bug fix courtesy Bill Arms u = self.random() -- cgit v0.12