Safe Haskell | None |
---|

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 `Int`

s.
The remaining bits will be truncated by `next`

.

- data CBRNG32
- mkCBRNG32 :: Integer -> CBRNG32
- restoreCBRNG32 :: CBRNGState -> CBRNG32
- data CBRNG64
- mkCBRNG64 :: Integer -> CBRNG64
- restoreCBRNG64 :: CBRNGState -> CBRNG64
- data CustomCBRNG32 k c
- mkCustomCBRNG32 :: LimitedInteger c => (k -> c -> c) -> k -> CustomCBRNG32 k c
- restoreCustomCBRNG32 :: (LimitedInteger k, LimitedInteger c) => (k -> c -> c) -> CBRNGState -> CustomCBRNG32 k c
- data CustomCBRNG64 k c
- mkCustomCBRNG64 :: LimitedInteger c => (k -> c -> c) -> k -> CustomCBRNG64 k c
- restoreCustomCBRNG64 :: (LimitedInteger k, LimitedInteger c) => (k -> c -> c) -> CBRNGState -> CustomCBRNG64 k c
- philox2 :: PhiloxWord a => a -> Array2 a -> Array2 a
- philox4 :: PhiloxWord a => Array2 a -> Array4 a -> Array4 a
- threefry2 :: (ThreefryWord a, Bits a, Num a) => Array2 a -> Array2 a -> Array2 a
- threefry4 :: (ThreefryWord a, Bits a, Num a) => Array4 a -> Array4 a -> Array4 a

# Default RNGs

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

Default 32-bit RNG.
Supports serialization through `Show`

/ `Read`

interface.
Alternatively, can be serialized with `getState`

and restored with `restoreCBRNG32`

.

restoreCBRNG32 :: CBRNGState -> CBRNG32Source

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

Default 64-bit RNG.
Supports serialization through `Show`

/ `Read`

interface.
Alternatively, can be serialized with `getState`

and restored with `restoreCBRNG64`

.

restoreCBRNG64 :: CBRNGState -> CBRNG64Source

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

(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 cSource

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

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

(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 cSource

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

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.

:: PhiloxWord a | |

=> a | key, |

-> Array2 a | counter, |

-> Array2 a | random number. |

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

:: PhiloxWord a | |

=> Array2 a | key, |

-> Array4 a | counter, |

-> Array4 a | random number. |

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

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