System.Random.Random123

This module is a Haskell port of the Random123 library (http://www.thesalmons.org/john/random123/). It is based on counter-based pseudo-random number generators (CBRNGs), which are, essentially, keyed bijections which transform successive counters into randomly distributed integers. For details about the theory behind the algorithms along with statistical and performance tests see the paper Salmon et al., P. Int. C. High. Perform. 16 (2011) (http://dx.doi.org/doi:10.1145/2063384.2063405).

The module exposes both bijection functions themselves (for customized approach) and instances of RandomGen.

Since CBRNGs are based on bijection functions, their periods are equal to the size of their corresponding counters. For example, 32-bit philox4 has Array4 Word32 counter, therefore the total counter size is 4 * 32 = 128 bit, and the period is 2^128.

RandomGen instances use each generated random array for several random integers, so their periods are several times bigger. Consider now that the philox4 bijection was used to create a CustomCBRNG64 generator. For each 64-bit Int its next function returns, it will use two of the elements of the Array4 Word32, so the total period is 2 * 2^128 = 2^129.

Note: There is no point in creating 64-bit RNGs when your platform has only 32-bit Ints. The remaining bits will be truncated by next.

Default RNGs

Use these if you want the (usually) optimal bijection algorithm, and serialization capabilities.

data CBRNG32

Default 32-bit RNG. Supports serialization through Show / Read interface. Alternatively, can be serialized with getState and restored with restoreCBRNG32.

Instances

Eq CBRNG32

Read CBRNG32

Show CBRNG32

RandomGen CBRNG32

SerializableCBRNG CBRNG32

mkCBRNG32 :: Integer -> CBRNG32

Creates a default 32-bit RNG (based on 32-bit philox4) with an Integer key.

restoreCBRNG32 :: CBRNGState -> CBRNG32

Restores a default 32-bit RNG from a saved state.

data CBRNG64

Default 64-bit RNG. Supports serialization through Show / Read interface. Alternatively, can be serialized with getState and restored with restoreCBRNG64.

Instances

Eq CBRNG64

Read CBRNG64

Show CBRNG64

RandomGen CBRNG64

SerializableCBRNG CBRNG64

mkCBRNG64 :: Integer -> CBRNG64

Creates a default 64-bit RNG (based on 64-bit philox4) with an Integer key.

restoreCBRNG64 :: CBRNGState -> CBRNG64

Restores a default 64-bit RNG from a saved state.

Custom RNGs

Use these if you want a custom bijection algorithm.

data CustomCBRNG32 k c

32-bit RNG with a custom bijection function. Can be serialized with getState and restored with restoreCustomCBRNG32 (but it is the user's responsibility to provide the original bijection).

Instances

(Counter c, Word32Array c) => RandomGen (CustomCBRNG32 k c)

(LimitedInteger k, LimitedInteger c) => SerializableCBRNG (CustomCBRNG32 k c)

mkCustomCBRNG32 :: LimitedInteger c => (k -> c -> c) -> k -> CustomCBRNG32 k c

Creates a custom 32-bit RNG from a keyed bijection (Word32- or Word64-parametrized version of philox2, philox2R, philox4, philox4R, threefry2, threefry2R, threefry4, threefry4R) and a corresponding key.

restoreCustomCBRNG32 :: (LimitedInteger k, LimitedInteger c) => (k -> c -> c) -> CBRNGState -> CustomCBRNG32 k c

Restores a custom 32-bit RNG from a saved state.

data CustomCBRNG64 k c

64-bit RNG with a custom bijection function. Can be serialized with getState and restored with restoreCustomCBRNG32 (but it is the user's responsibility to provide the original bijection).

Instances

(Counter c, Word64Array c) => RandomGen (CustomCBRNG64 k c)

(LimitedInteger k, LimitedInteger c) => SerializableCBRNG (CustomCBRNG64 k c)

mkCustomCBRNG64 :: LimitedInteger c => (k -> c -> c) -> k -> CustomCBRNG64 k c

Creates a custom 64-bit RNG from a keyed bijection (Word32- or Word64-parametrized version of philox2, philox2R, philox4, philox4R, threefry2, threefry2R, threefry4, threefry4R) and a corresponding key.

restoreCustomCBRNG64 :: (LimitedInteger k, LimitedInteger c) => (k -> c -> c) -> CBRNGState -> CustomCBRNG64 k c

Restores a custom 64-bit RNG from a saved state.

Keyed bijection functions

Use these if you want the ultimate control over keys and counters. Sometimes it is advantageous to bind part of the counter or the key the node or thread identifier, or to indices of a time or space grid. You can use liFromInteger (or just a tuple constructor) to create keys and counters, and skip and increment to change counter values.

If you want further control over the number of rounds in these bijections, see System.Random.Random123.Philox and System.Random.Random123.Threefry modules.

philox2

Arguments

:: PhiloxWord a

=> a

key,

-> Array2 a

counter,

-> Array2 a

random number.

Generates a Philox-2 random number with the optimal number of rounds.

philox4

Arguments

:: PhiloxWord a

=> Array2 a

key,

-> Array4 a

counter,

-> Array4 a

random number.

Generates a Philox-4 random number with the optimal number of rounds.

threefry2

Arguments

:: (ThreefryWord a, Bits a, Num a)

=> Array2 a

key,

-> Array2 a

counter,

-> Array2 a

random number.

Generates a Threefry-2 random number with the optimal number of rounds.

threefry4

Arguments

:: (ThreefryWord a, Bits a, Num a)

=> Array4 a

key,

-> Array4 a

counter,

-> Array4 a

random number.

Generates a Threefry-4 random number with the optimal number of rounds.