Pseudo-random number generation. This module contains code for generating high quality random numbers that follow a uniform distribution.

For non-uniform distributions, see the Distributions module.

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.

The generator state is stored in the Gen data type. It can be created in several ways:

1. Using the withSystemRandom call, which creates a random state.
2. Supply your own seed to initialize function.
3. Finally, create makes a generator from a fixed seed. Generators created in this way aren't really random.

For repeatability, the state of the generator can be snapshotted and replayed using the save and restore functions.

The simplest use is to generate a vector of uniformly distributed values:

  vs <- withSystemRandom . asGenST $ \gen -> uniformVector gen 100

These values can be of any type which is an instance of the class Variate.

To generate random values on demand, first create a random number generator.

  gen <- create

Hold onto this generator and use it wherever random values are required (creating a new generator is expensive compared to generating a random number, so you don't want to throw them away). Get a random value using uniform or uniformR:

  v <- uniform gen

  v <- uniformR (1, 52) gen

The functions in this package are deliberately written for flexibility, and will run in both the IO and ST monads.

This can defeat the compiler's ability to infer a principal type in simple (and common) cases. For instance, we would like the following to work cleanly:

import System.Random.MWC
import Data.Vector.Unboxed

main = do
  v <- withSystemRandom $ \gen -> uniformVector gen 20
  print (v :: Vector Int)

Unfortunately, the compiler cannot tell what monad uniformVector should execute in. The "fix" of adding explicit type annotations is not pretty:

{-# LANGUAGE ScopedTypeVariables #-}

import Control.Monad.ST

main = do
  vs <- withSystemRandom $
        \(gen::GenST s) -> uniformVector gen 20 :: ST s (Vector Int)
  print vs

As a more readable alternative, this library provides asGenST and asGenIO to constrain the types appropriately. We can get rid of the explicit type annotations as follows:

main = do
  vs <- withSystemRandom . asGenST $ \gen -> uniformVector gen 20
  print (vs :: Vector Int)

This is almost as compact as the original code that the compiler rejected.

• Marsaglia, G. (2003) Seeds for random number generators. Communications of the ACM 46(5):90–93. http://doi.acm.org/10.1145/769800.769827
• 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