random — Генерация псевдослучайных чисел

Исходный код: Lib/random.py

Этот модуль реализует генераторы псевдослучайных чисел для различных распределений.

Для целых чисел — равномерный выбор из диапазона. Для последовательностей — равномерный выбор случайного элемента, функция для генерации случайной перестановки списка на месте и функция для случайной выборки без возвращения.

На вещественной прямой есть функции для вычисления равномерного, нормального (гауссового), логнормального, отрицательного экспоненциального, гамма и бета распределений. Для генерации распределений углов доступно распределение Вишмана.

Практически все функции модуля зависят от базовой функции random(), которая генерирует случайное число с плавающей точкой равномерно в полуоткрытом интервале [0.0, 1.0). Python использует Mersenne Twister в качестве основного генератора. Он генерирует числа с плавающей точкой точностью 53 бита и имеет период 2¹⁹⁹³⁷-1. Базовая реализация на C быстрая и потокобезопасная. Mersenne Twister — один из самых широко протестированных генераторов псевдослучайных чисел. Однако, будучи полностью детерминированным, он не подходит для всех целей и совершенно непригоден для криптографических целей.

Функции, предоставляемые этим модулем, фактически являются связанными методами скрытого экземпляра класса random.Random. Вы можете создать свои экземпляры класса Random, чтобы получить генераторы, которые не разделяют состояние. Это особенно полезно для многопоточных программ, создания отдельного экземпляра Random для каждого потока и использования метода jumpahead(), чтобы сделать вероятным, что сгенерированные последовательности, видимые каждому потоку, не перекрываются.

Класс Random также может быть подклассом, если вы хотите использовать другой базовый генератор по своему усмотрению: в этом случае переопределите методы random(), seed(), getstate(), setstate() и jumpahead(). В качестве необязательной функции новый генератор может предоставить метод getrandbits() — это позволяет randrange() генерировать выборки по произвольно большому диапазону.

В качестве примера наследования, модуль random предоставляет класс WichmannHill, который реализует альтернативный генератор на чистом Python. Класс обеспечивает обратную совместимость для воспроизведения результатов из более ранних версий Python, которые использовали алгоритм Вишмана-Хилла в качестве основного генератора. Обратите внимание, что этот генератор Вишмана-Хилла больше не рекомендуется: его период слишком короткий по современным стандартам, а сгенерированная последовательность известна тем, что не проходит строгие тесты на случайность. См. ссылки ниже для получения подробностей по недавней модификации, устраняющей эти недостатки.

Модуль random также предоставляет класс SystemRandom, который использует системную функцию os.urandom() для генерации случайных чисел из источников, предоставляемых операционной системой.

Функции ведения учета:

random.seed(a=None)

Инициализирует внутреннее состояние генератора псевдослучайных чисел.

None или без аргумента, сеет из текущего времени или из специфичного для операционной системы источника случайности, если он доступен (см. функцию os.urandom() для получения подробной информации об его доступности).

Если a не None или не int или long, используется hash(a). Обратите внимание, что значения хеширования для некоторых типов не детерминированы, когда включен PYTHONHASHSEED.

Изменено в версии 2.4: ранее ресурсы операционной системы не использовались.

random.getstate()

Возвращает объект, захватывающий текущее внутреннее состояние генератора. Этот объект можно передать в setstate() для восстановления состояния.

Новая в версии 2.1.

Изменено в версии 2.6: Значения состояния, созданные в Python 2.6, не могут быть загружены в более ранние версии.

random.setstate(state)

state должен был быть получен из предыдущего вызова getstate(), и setstate() восстанавливает внутреннее состояние генератора до того состояния, в котором оно находилось во время вызова getstate().

Новая в версии 2.1.

random.jumpahead(n)

Изменяет внутреннее состояние на состояние, отличное от текущего и, вероятно, находящееся далеко от него. n — неотрицательное целое число, используемое для перемешивания текущего вектора состояния. Это наиболее полезно в многопоточных программах в сочетании с несколькими экземплярами класса Random: setstate() или seed() могут быть использованы для принудительного приведения всех экземпляров к одному внутреннему состоянию, а затем jumpahead() может быть использован для принудительного разделения состояний экземпляров.

Новая в версии 2.1.

Изменено в версии 2.3: Вместо перехода к конкретному состоянию, на n шагов вперед, jumpahead(n) переходит в другое состояние, вероятно, отделённое многими шагами.

random.getrandbits(k)

Возвращает целое число Python long с k случайными битами. Этот метод предоставляется генератором MersenneTwister, и некоторые другие генераторы также могут предоставить его в качестве необязательной части API. Когда доступен, getrandbits() позволяет randrange() обрабатывать произвольно большие диапазоны.

Новая в версии 2.4.

Функции для целых чисел:

random.randrange(stop)

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

Возвращает случайно выбранный элемент из range(start, stop, step). Это эквивалентно choice(range(start, stop, step)), но фактически не создаёт объект диапазона.

Новая в версии 1.5.2.

random.randint(a, b)

Возвращает случайное целое число N, такое что a <= N <= b.

Функции для последовательностей:

random.choice(seq)

Возвращает случайный элемент из непустой последовательности seq. Если seq пуста, возбуждается исключение IndexError.

random.shuffle(x[, random])

Перемешивает последовательность x на месте. Необязательный аргумент random — функция без аргументов, возвращающая случайное число с плавающей точкой в диапазоне [0.0, 1.0); по умолчанию это функция random().

Обратите внимание, что даже для довольно небольших len(x), общее число перестановок x больше, чем период большинства генераторов псевдослучайных чисел; это означает, что большинство перестановок длинной последовательности никогда не могут быть сгенерированы.

random.sample(population, k)

Возвращает список длиной k, содержащий уникальные элементы, выбранные из последовательности population. Используется для случайной выборки без возвращения.

Новая функция в версии 2.3.

Возвращает новый список, содержащий элементы из population, не изменяя исходную последовательность. Результирующий список отсортирован по порядку выбора, так что все подсписки также будут являться допустимыми случайными выборками. Это позволяет разделить победителей лотереи (выборка) на победителей главного приза и призёров второго места (подсписки).

Элементы population не обязательно должны быть хешируемыми или уникальными. Если population содержит повторяющиеся элементы, каждое вхождение является возможным элементом для выборки.

Для выбора выборки из диапазона целых чисел используйте объект xrange() в качестве аргумента. Это особенно быстро и экономично по памяти при выборке из большой population: sample(xrange(10000000), 60).

Следующие функции генерируют определённые распределения действительных чисел. Имена параметров функций соответствуют переменным в уравнениях распределений, как это принято в математической практике; большинство этих уравнений можно найти в любом учебнике по статистике.

random.random()

Возвращает следующее случайное число с плавающей точкой в диапазоне [0.0, 1.0).

random.uniform(a, b)

Возвращает случайное число с плавающей точкой N, такое что a <= N <= b для a <= b и b <= N <= a для b < a.

Значение конечной точки b может или не может быть включено в диапазон, в зависимости от округления чисел с плавающей точкой в уравнении a + (b-a) * random().

random.triangular(low, high, mode)

Возвращает случайное число с плавающей точкой N, такое что low <= N <= high и со значением mode внутри этих границ. Границы low и high по умолчанию равны 0 и 1. Аргумент mode по умолчанию равен серединному значению между границами, что даёт симметричное распределение.

Новая функция в версии 2.6.

random.betavariate(alpha, beta)

Бета-распределение. Условия на параметры — alpha > 0 и beta > 0. Возвращаемые значения лежат в диапазоне от 0 до 1.

random.expovariate(lambd)

Экспоненциальное распределение. lambd равно 1,0, делённому на желаемое среднее значение. Оно должно быть отличным от нуля. (Параметр был бы назван «lambda», но это ключевое слово в Python.) Возвращаемые значения лежат в диапазоне от 0 до положительной бесконечности, если lambd положительно, и от отрицательной бесконечности до 0, если lambd отрицательно.

random.gammavariate(alpha, beta)

Гамма-распределение. (Не гамма-функция!) Условия на параметры — alpha > 0 и beta > 0.

Функция плотности вероятности:

          x ** (alpha - 1) * math.exp(-x / beta)
pdf(x) =  --------------------------------------
            math.gamma(alpha) * beta ** alpha

random.gauss(mu, sigma)

Гауссово распределение. mu — среднее значение, а sigma — стандартное отклонение. Это немного быстрее, чем функция normalvariate(), определённая ниже.

random.lognormvariate(mu, sigma)

Логарифмически нормальное распределение. Если взять натуральный логарифм этого распределения, получится нормальное распределение со средним значением mu и стандартным отклонением sigma. mu может принимать любые значения, а sigma должно быть больше нуля.

random.normalvariate(mu, sigma)

Нормальное распределение. mu — среднее значение, а sigma — стандартное отклонение.

random.vonmisesvariate(mu, kappa)

mu — средний угол, выраженный в радианах от 0 до 2*pi, а kappa — параметр концентрации, который должен быть больше или равен нулю. Если kappa равно нулю, это распределение сводится к равномерному случайному углу в диапазоне от 0 до 2*pi.

random.paretovariate(alpha)

Распределение Парето. alpha — параметр формы.

random.weibullvariate(alpha, beta)

Распределение Вейбулла. alpha — параметр масштаба, а beta — параметр формы.

Альтернативные генераторы:

class random.WichmannHill([seed])

Класс, реализующий алгоритм Вичмана-Хилла в качестве основного генератора. Имеет все те же методы, что и Random плюс метод whseed(), описанный ниже. Поскольку этот класс реализован на чистом Python, он не потокобезопасен и может потребовать блокировок между вызовами. Период генератора составляет 6 953 607 871 644, что достаточно мало, чтобы потребовать осторожности, чтобы две независимые случайные последовательности не перекрывались.

random.whseed([x])

Этот метод устарел и предоставляется для совместимости на битовом уровне с версиями Python до 2.1. См. seed() для получения подробностей. whseed() не гарантирует, что различные целочисленные аргументы дают различные внутренние состояния, и может обеспечить не более 2²⁴ различных внутренних состояний в целом.

class random.SystemRandom([seed])

Класс, использующий функцию os.urandom() для генерации случайных чисел из источников, предоставленных операционной системой. Не доступен на всех системах. Не полагается на состояние программного обеспечения, и последовательности не воспроизводимы. Соответственно, методы seed() и jumpahead() не имеют эффекта и игнорируются. Методы getstate() и setstate() вызывают исключение NotImplementedError, если они вызываются.

Новая функция в версии 2.4.

Примеры основного использования:

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