9.6. random — Gera números pseudoaleatórios

Código Fonte: Lib/random.py

Este módulo implementa geradores de números pseudoaleatórios para várias distribuições.

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.

Na linha real, existem funções para calcular distribuições uniforme, normal (gaussiana), lognormal, exponencial negativa, gama e beta. Para gerar distribuições de ângulos, a distribuição de von Mises está disponível.

Quase todas as funções do módulo dependem da função básica random(), que gera um ponto flutuante aleatório uniformemente no intervalo semiaberto [0.0, 1.0). O Python usa o Mersenne Twister como gerador de núcleo. Produz pontos flutuantes de precisão de 53 bits e possui um período de 2**19937-1. A implementação subjacente em C é rápida e segura para threads. O Mersenne Twister é um dos geradores de números aleatórios mais amplamente testados existentes. No entanto, sendo completamente determinístico, não é adequado para todos os fins e é totalmente inadequado para fins criptográficos.

The functions supplied by this module are actually bound methods of a hidden instance of the random.Random class. You can instantiate your own instances of Random to get generators that don’t share state. This is especially useful for multi-threaded programs, creating a different instance of Random for each thread, and using the jumpahead() method to make it likely 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 random(), seed(), getstate(), setstate() and jumpahead() methods. Optionally, a new generator can supply a getrandbits() method — this allows randrange() to produce selections over an arbitrarily large range.

Novo na versão 2.4: the getrandbits() method.

As an example of subclassing, the random module provides the 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.

Alterado na versão 2.3: MersenneTwister replaced Wichmann-Hill as the default generator.

O módulo random também fornece a classe SystemRandom que usa a função do sistema os.urandom() para gerar números aleatórios a partir de fontes fornecidas pelo sistema operacional.

Aviso

The pseudo-random generators of this module should not be used for security purposes. Use os.urandom() or SystemRandom if you require a cryptographically secure pseudo-random number generator.

Bookkeeping functions:

random.seed(a=None)

Initialize internal state of the random number generator.

None or no argument seeds from current time or from an operating system specific randomness source if available (see the os.urandom() function for details on availability).

If a is not None or an int or a long, then hash(a) is used instead. Note that the hash values for some types are nondeterministic when PYTHONHASHSEED is enabled.

Alterado na versão 2.4: formerly, operating system resources were not used.

random.getstate()

Retorna um objeto capturando o estado interno atual do gerador. Este objeto pode ser passado para setstate() para restaurar o estado.

Novo na versão 2.1.

Alterado na versão 2.6: State values produced in Python 2.6 cannot be loaded into earlier versions.

random.setstate(state)

state deveria ter sido obtido de uma chamada anterior para getstate(), e setstate() restaura o estado interno do gerador para o que era no momento getstate() foi chamado.

Novo na versão 2.1.

random.jumpahead(n)

Change the internal state to one different from and likely far away from the current state. n is a non-negative integer which is used to scramble the current state vector. This is most useful in multi-threaded programs, in conjunction with multiple instances of the Random class: setstate() or seed() can be used to force all instances into the same internal state, and then jumpahead() can be used to force the instances’ states far apart.

Novo na versão 2.1.

Alterado na versão 2.3: Instead of jumping to a specific state, n steps ahead, jumpahead(n) jumps to another state likely to be separated by many steps.

random.getrandbits(k)

Returns a python long int with 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, getrandbits() enables randrange() to handle arbitrarily large ranges.

Novo na versão 2.4.

Functions for integers:

random.randrange(stop)
random.randrange(start, stop[, step])

Retorna um elemento selecionado aleatoriamente em range(start, stop, step). Isso é equivalente a choice(range(start, stop, step)), mas na verdade não cria um objeto range.

Novo na versão 1.5.2.

random.randint(a, b)

Return a random integer N such that a <= N <= b.

Functions for sequences:

random.choice(seq)

Retorna um elemento aleatório da sequência não vazia seq. Se seq estiver vazio, levanta IndexError.

random.shuffle(x[, random])

Shuffle the sequence x in place. The optional argument random is a 0-argument function returning a random float in [0.0, 1.0); by default, this is the function random().

Note that for even rather small len(x), the total number of permutations of x is larger than the period of most random number generators; this implies that most permutations of a long sequence can never be generated.

random.sample(population, k)

Return a k length list of unique elements chosen from the population sequence. Used for random sampling without replacement.

Novo na versão 2.3.

Retorna uma nova lista contendo elementos da população, mantendo a população original inalterada. A lista resultante está na ordem de seleção, para que todas as sub-fatias também sejam amostras aleatórias válidas. Isso permite que os vencedores do sorteio (a amostra) sejam divididos em grandes prêmios e vencedores de segundo lugar (as sub-fatias).

Os membros da população não precisam ser hasheáveis ou único. Se a população contiver repetições, cada ocorrência é uma seleção possível na amostra.

To choose a sample from a range of integers, use an xrange() object as an argument. This is especially fast and space efficient for sampling from a large population: sample(xrange(10000000), 60).

As funções a seguir geram distribuições específicas com valor real. Os parâmetros de função são nomeados após as variáveis correspondentes na equação da distribuição, conforme usadas na prática matemática comum; a maioria dessas equações pode ser encontrada em qualquer texto estatístico.

random.random()

Retorna o próximo número de ponto flutuante aleatório no intervalo [0.0, 1.0).

random.uniform(a, b)

Retorna um número de ponto flutuante aleatório N de forma que a <= N <= b para a <= b e b <= N <= a para b < a.

O valor do ponto final b pode ou não ser incluído no intervalo, dependendo do arredondamento do ponto flutuante na equação a + (b-a) * random().

random.triangular(low, high, mode)

Retorna um número de ponto flutuante aleatório N de forma que low <= N <= high e com o modo mode especificado entre esses limites. Os limites low e high são padronizados como zero e um. O argumento mode assume como padrão o ponto médio entre os limites, fornecendo uma distribuição simétrica.

Novo na versão 2.6.

random.betavariate(alpha, beta)

Distribuição beta. As condições nos parâmetros são alpha > 0 e beta > 0. Os valores retornados variam entre 0 e 1.

random.expovariate(lambd)

Distribuição exponencial. lambd é 1.0 dividido pela média desejada. Deve ser diferente de zero. (O parâmetro seria chamado “lambda”, mas é uma palavra reservada em Python.) Os valores retornados variam de 0 a infinito positivo se lambd for positivo e de infinito negativo a 0 se lambd for negativo.

random.gammavariate(alpha, beta)

Distribuição gama. (Não a função gama!) As condições nos parâmetros são alpha > 0 e beta > 0.

A função de distribuição de probabilidade é:

          x ** (alpha - 1) * math.exp(-x / beta)
pdf(x) =  --------------------------------------
            math.gamma(alpha) * beta ** alpha
random.gauss(mu, sigma)

Distribuição gaussiana. mu é a média e sigma é o desvio padrão. Isso é um pouco mais rápido que a função normalvariate() definida abaixo.

random.lognormvariate(mu, sigma)

Distribuição log normal. Se você usar o logaritmo natural dessa distribuição, obterá uma distribuição normal com média mu e desvio padrão sigma. mu pode ter qualquer valor e sigma deve ser maior que zero.

random.normalvariate(mu, sigma)

Distribuição normal. mu é a média e sigma é o desvio padrão.

random.vonmisesvariate(mu, kappa)

mu é o ângulo médio, expresso em radianos entre 0 e 2*pi, e kappa é o parâmetro de concentração, que deve ser maior ou igual a zero. Se kappa for igual a zero, essa distribuição será reduzida para um ângulo aleatório uniforme no intervalo de 0 a 2*pi.

random.paretovariate(alpha)

Distribuição de Pareto. alpha é o parâmetro de forma.

random.weibullvariate(alpha, beta)

Distribuição Weibull. alpha é o parâmetro de escala e beta é o parâmetro de forma.

Alternative Generators:

class random.WichmannHill([seed])

Class that implements the Wichmann-Hill algorithm as the core generator. Has all of the same methods as Random plus the 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.

random.whseed([x])

This is obsolete, supplied for bit-level compatibility with versions of Python prior to 2.1. See seed() for details. 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.

class random.SystemRandom([seed])

Class that uses the 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 seed() and jumpahead() methods have no effect and are ignored. The getstate() and setstate() methods raise NotImplementedError if called.

Novo na versão 2.4.

Examples of basic usage:

>>> 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]

Ver também

M. Matsumoto and T. Nishimura, “Mersenne Twister: A 623-dimensionally equidistributed uniform pseudorandom number generator”, ACM Transactions on Modeling and Computer Simulation Vol. 8, No. 1, January pp.3–30 1998.

Wichmann, B. A. & Hill, I. D., “Algorithm AS 183: An efficient and portable pseudo-random number generator”, Applied Statistics 31 (1982) 188-190.

Complementary-Multiply-with-Carry recipe for a compatible alternative random number generator with a long period and comparatively simple update operations.