Portability | portable |
---|---|

Stability | experimental |

Maintainer | bos@serpentine.com |

Pseudo-random variate generation.

- data Gen s
- data Seed
- class Variate a where
- normal :: Gen s -> ST s Double
- create :: ST s (Gen s)
- initialize :: UArr Word32 -> ST s (Gen s)
- withSystemRandom :: (forall s. Gen s -> ST s a) -> IO a
- save :: Gen s -> ST s Seed
- restore :: Seed -> ST s (Gen s)
- uniformArray :: (UA a, Variate a) => Gen s -> Int -> ST s (UArr a)

# Types

An immutable snapshot of the state of a `Gen`

.

The class of types for which we can generate uniformly distributed random variates.

The uniform PRNG uses Marsaglia's MWC256 (also known as MWC8222) multiply-with-carry generator, which has a period of 2^8222 and fares well in tests of randomness. It is also extremely fast, between 2 and 3 times faster than the Mersenne Twister.

*Note*: Marsaglia's PRNG is not known to be cryptographically
secure, so you should not use it for cryptographic operations.

uniform :: Gen s -> ST s aSource

Generate a single uniformly distributed random variate. The range of values produced varies by type:

- For fixed-width integral types, the type's entire range is used.
- For floating point numbers, the range (0,1] is used. Zero is
explicitly excluded, to allow variates to be used in
statistical calculations that require non-zero values
(e.g. uses of the
`log`

function). - The range of random
`Integer`

variates is the same as for`Int`

.

To generate a `Float`

variate with a range of [0,1), subtract
2**(-33). To do the same with `Double`

variates, subtract
2**(-53).

Variate Bool | |

Variate Double | |

Variate Float | |

Variate Int | |

Variate Int8 | |

Variate Int16 | |

Variate Int32 | |

Variate Int64 | |

Variate Integer | |

Variate Word | |

Variate Word8 | |

Variate Word16 | |

Variate Word32 | |

Variate Word64 | |

(Variate a, Variate b) => Variate (a, b) | |

(Variate a, Variate b, Variate c) => Variate (a, b, c) | |

(Variate a, Variate b, Variate c, Variate d) => Variate (a, b, c, d) |

# Other distributions

normal :: Gen s -> ST s DoubleSource

Generate a normally distributed random variate.

The implementation uses Doornik's modified ziggurat algorithm. Compared to the ziggurat algorithm usually used, this is slower, but generates more independent variates that pass stringent tests of randomness.

# Creation

initialize :: UArr Word32 -> ST s (Gen s)Source

Create a generator for variates using the given seed, of which up to 256 elements will be used. For arrays of less than 256 elements, part of the default seed will be used to finish initializing the generator's state.

Examples:

initialize (singletonU 42)

initialize (toU [4, 8, 15, 16, 23, 42])

If a seed contains fewer than 256 elements, it is first used
verbatim, then its elements are `xor`

ed against elements of the
default seed until 256 elements are reached.

withSystemRandom :: (forall s. Gen s -> ST s a) -> IO aSource

Seed a PRNG with data from the system's fast source of pseudo-random numbers ("/dev/urandom" on Unix-like systems), then run the given action.

*Note*: on Windows, this code does not yet use the native
Cryptographic API as a source of random numbers (it uses the system
clock instead). As a result, the sequences it generates may not be
highly independent.

# State management

# Helper functions

uniformArray :: (UA a, Variate a) => Gen s -> Int -> ST s (UArr a)Source

Generate an array of pseudo-random variates. This is not
necessarily faster than invoking `uniform`

repeatedly in a loop,
but it may be more convenient to use in some situations.

# References

- Doornik, J.A. (2005) An improved ziggurat method to generate normal random samples. Mimeo, Nuffield College, University of Oxford. http://www.doornik.com/research/ziggurat.pdf
- Doornik, J.A. (2007) Conversion of high-period random numbers to
floating point.
*ACM Transactions on Modeling and Computer Simulation*17(1). http://www.doornik.com/research/randomdouble.pdf - Marsaglia, G. (2003) Seeds for random number generators.
*Communications of the ACM*46(5):90–93. http://doi.acm.org/10.1145/769800.769827 - Thomas, D.B.; Leong, P.G.W.; Luk, W.; Villasenor, J.D.
(2007). Gaussian random number generators.
*ACM Computing Surveys*39(4). http://www.cse.cuhk.edu.hk/~phwl/mt/public/archives/papers/grng_acmcs07.pdf