Random123-0.2.0: Haskell port of Random123 library

Safe HaskellNone
LanguageHaskell98

System.Random.Random123

Contents

Description

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.

Synopsis

Default RNGs

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

data CBRNG32 Source

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

mkCBRNG32 :: Integer -> CBRNG32 Source

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

restoreCBRNG32 :: CBRNGState -> CBRNG32 Source

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

data CBRNG64 Source

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

mkCBRNG64 :: Integer -> CBRNG64 Source

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

restoreCBRNG64 :: CBRNGState -> CBRNG64 Source

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 Source

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).

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

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 Source

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

data CustomCBRNG64 k c Source

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).

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

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 Source

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 Source

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 Source

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 Source

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 Source

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.