std.random

Facilities for random number generation.

Disclaimer: The random number generators and API provided in this module are not designed to be cryptographically secure, and are therefore unsuitable for cryptographic or security-related purposes such as generating authentication tokens or network sequence numbers. For such needs, please use a reputable cryptographic library instead.

The new-style generator objects hold their own state so they are immune of threading issues. The generators feature a number of well-known and well-documented methods of generating random numbers. An overall fast and reliable means to generate random numbers is the Mt19937 generator, which derives its name from "Mersenne Twister with a period of 2 to the power of 19937". In memory-constrained situations, linear congruential generators such as MinstdRand0 and MinstdRand might be useful. The standard library provides an alias Random for whichever generator it considers the most fit for the target environment.

In addition to random number generators, this module features distributions, which skew a generator's output statistical distribution in various ways. So far the uniform distribution for integers and real numbers have been implemented.

Members

Aliases

MinstdRand
alias MinstdRand = LinearCongruentialEngine!(uint, 48_271, 0, 2_147_483_647)

Define LinearCongruentialEngine generators with well-chosen parameters. MinstdRand0 implements Park and Miller's "minimal standard" generator that uses 16807 for the multiplier. MinstdRand implements a variant that has slightly better spectral behavior by using the multiplier 48271. Both generators are rather simplistic.

MinstdRand0
alias MinstdRand0 = LinearCongruentialEngine!(uint, 16_807, 0, 2_147_483_647)

Define LinearCongruentialEngine generators with well-chosen parameters. MinstdRand0 implements Park and Miller's "minimal standard" generator that uses 16807 for the multiplier. MinstdRand implements a variant that has slightly better spectral behavior by using the multiplier 48271. Both generators are rather simplistic.

Mt19937
alias Mt19937 = MersenneTwisterEngine!(uint, 32, 624, 397, 31, 0x9908b0df, 11, 0xffffffff, 7, 0x9d2c5680, 15, 0xefc60000, 18, 1_812_433_253)

A MersenneTwisterEngine instantiated with the parameters of the original engine MT19937, generating uniformly-distributed 32-bit numbers with a period of 2 to the power of 19937. Recommended for random number generation unless memory is severely restricted, in which case a LinearCongruentialEngine would be the generator of choice.

Mt19937_64
alias Mt19937_64 = MersenneTwisterEngine!(ulong, 64, 312, 156, 31, 0xb5026f5aa96619e9, 29, 0x5555555555555555, 17, 0x71d67fffeda60000, 37, 0xfff7eee000000000, 43, 6_364_136_223_846_793_005)

A MersenneTwisterEngine instantiated with the parameters of the original engine MT19937-64, generating uniformly-distributed 64-bit numbers with a period of 2 to the power of 19937.

Random
alias Random = Mt19937

The "default", "favorite", "suggested" random number generator type on the current platform. It is an alias for one of the previously-defined generators. You may want to use it if (1) you need to generate some nice random numbers, and (2) you don't care for the minutiae of the method being used.

Xorshift32
alias Xorshift32 = XorshiftEngine!(uint, 32, 13, 17, 15)

Define XorshiftEngine generators with well-chosen parameters. See each bits examples of "Xorshift RNGs". Xorshift is a Xorshift128's alias because 128bits implementation is mostly used.

Functions

choice
auto ref choice(Range range, RandomGen urng)
auto ref choice(Range range)

Returns a random, uniformly chosen, element e from the supplied Range range. If no random number generator is passed, the default rndGen is used.

dice
size_t dice(Rng rnd, Num[] proportions)
size_t dice(R rnd, Range proportions)
size_t dice(Range proportions)
size_t dice(Num[] proportions)

Rolls a dice with relative probabilities stored in proportions. Returns the index in proportions that was chosen.

partialShuffle
Range partialShuffle(Range r, size_t n, RandomGen gen)
Range partialShuffle(Range r, size_t n)

Partially shuffles the elements of r such that upon returning r[0 .. n] is a random subset of r and is randomly ordered. r[n .. r.length] will contain the elements not in r[0 .. n]. These will be in an undefined order, but will not be random in the sense that their order after partialShuffle returns will not be independent of their order before partialShuffle was called.

randomCover
auto randomCover(Range r, UniformRNG rng)
auto randomCover(Range r)

Covers a given range r in a random manner, i.e. goes through each element of r once and only once, just in a random order. r must be a random-access range with length.

randomSample
auto randomSample(Range r, size_t n)
auto randomSample(Range r, size_t n, size_t total, UniformRNG rng)
auto randomSample(Range r, size_t n, size_t total)
auto randomSample(Range r, size_t n, UniformRNG rng)

Selects a random subsample out of r, containing exactly n elements. The order of elements is the same as in the original range. The total length of r must be known. If total is passed in, the total number of sample is considered to be total. Otherwise, RandomSample uses r.length.

randomShuffle
Range randomShuffle(Range r, RandomGen gen)
Range randomShuffle(Range r)

Shuffles elements of r using gen as a shuffler. r must be a random-access range with length. If no RNG is specified, rndGen will be used.

uniform
auto uniform(T1 a, T2 b)
auto uniform(T1 a, T2 b, UniformRandomNumberGenerator urng)

Generates a number between a and b. The boundaries parameter controls the shape of the interval (open vs. closed on either side). Valid values for boundaries are "[]", "$(LPAREN)]", "[$(RPAREN)", and "()". The default interval is closed to the left and open to the right. The version that does not take urng uses the default generator rndGen.

uniform
auto uniform(UniformRandomNumberGenerator urng)
auto uniform()

Generates a uniformly-distributed number in the range [T.min, T.max] for any integral or character type T. If no random number generator is passed, uses the default rndGen.

uniform01
T uniform01()
T uniform01(UniformRNG rng)

Generates a uniformly-distributed floating point number of type T in the range [0, 1). If no random number generator is specified, the default RNG rndGen will be used as the source of randomness.

uniformDistribution
F[] uniformDistribution(size_t n, F[] useThis)

Generates a uniform probability distribution of size n, i.e., an array of size n of positive numbers of type F that sum to 1. If useThis is provided, it is used as storage.

Properties

rndGen
Random rndGen [@property getter]

Global random number generator used by various functions in this module whenever no generator is specified. It is allocated per-thread and initialized to an unpredictable value for each thread.

unpredictableSeed
uint unpredictableSeed [@property getter]

A "good" seed for initializing random number engines. Initializing with unpredictableSeed makes engines generate different random number sequences every run.

Structs

LinearCongruentialEngine
struct LinearCongruentialEngine(UIntType, UIntType a, UIntType c, UIntType m)

Linear Congruential generator. When m = 0, no modulus is used.

MersenneTwisterEngine
struct MersenneTwisterEngine(UIntType, size_t w, size_t n, size_t m, size_t r, UIntType a, size_t u, UIntType d, size_t s, UIntType b, size_t t, UIntType c, size_t l, UIntType f)

The Mersenne Twister generator.

RandomCover
struct RandomCover(Range, UniformRNG = void)

Covers a given range r in a random manner, i.e. goes through each element of r once and only once, just in a random order. r must be a random-access range with length.

RandomSample
struct RandomSample(Range, UniformRNG = void)

Selects a random subsample out of r, containing exactly n elements. The order of elements is the same as in the original range. The total length of r must be known. If total is passed in, the total number of sample is considered to be total. Otherwise, RandomSample uses r.length.

XorshiftEngine
struct XorshiftEngine(UIntType, uint nbits, int sa, int sb, int sc)
template XorshiftEngine(UIntType, int bits, int a, int b, int c)

Xorshift generator. Implemented according to Xorshift RNGs (Marsaglia, 2003) when the size is small. For larger sizes the generator uses Sebastino Vigna's optimization of using an index to avoid needing to rotate the internal array.

Templates

isSeedable
template isSeedable(Rng, SeedType)
template isSeedable(Rng)

Test if Rng is seedable. The overload taking a SeedType also makes sure that the Rng can be seeded with SeedType.

isUniformRNG
template isUniformRNG(Rng, ElementType)
template isUniformRNG(Rng)

Test if Rng is a random-number generator. The overload taking a ElementType also makes sure that the Rng generates values of that type.

unpredictableSeed
template unpredictableSeed(UIntType)

A "good" seed for initializing random number engines. Initializing with unpredictableSeed makes engines generate different random number sequences every run.

Meta

Credits

The entire random number library architecture is derived from the excellent C++0X random number facility proposed by Jens Maurer and contributed to by researchers at the Fermi laboratory (excluding Xorshift).

Authors

Andrei Alexandrescu Masahiro Nakagawa (Xorshift random generator) Joseph Rushton Wakeling (Algorithm D for random sampling) Ilya Yaroshenko (Mersenne Twister implementation, adapted from mir-random)