Pseudo-random number generation using 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. There're two representation of generator: Gen which is generator that uses in-place mutation and Seed which is immutable snapshot of generator's state.

Initialization

Generator could be initialized in several ways. One is to obtain randomness from operating system using createSystemRandom, createSystemSeed or withSystemRandomST (All examples assume that System.Random.Stateful is imported)

>>> g <- createSystemRandom
>>> uniformM g :: IO Int
...

>>> withSystemRandomST $ \g -> uniformM g :: IO Int
...

Deterministically create generator from given seed using initialize function:

>>> import qualified Data.Vector.Unboxed as U
>>> import System.Random.Stateful
>>> g <- initialize $ U.fromList [1,2,3]
>>> uniformRM (1,200) g :: IO Int
101

Last way is to create generator with fixed seed which could be useful in testing

>>> g <- create
>>> uniformM g :: IO Int
-8765701622605876598

Generation of random numbers

Recommended way of generating random numbers in simple cases like generating uniformly distributed random number in range or value uniformly distributed in complete type domain is to use UniformRange and Uniform type classes. Note that while small self-contained examples usually require explicit annotations usually result type could be inferred.

This example simulates 20 throws of fair 6-sided dice:

>>> g <- create
>>> replicateM 20 $ uniformRM (1, 6::Integer) g
[3,4,3,1,4,6,1,6,1,4,2,2,3,2,4,2,5,1,3,5]

For generating full range of possible values one could use uniformM. This example generates 10 random bytes, or equivalently 10 throws of 256-sided dice:

>>> g <- create
>>> replicateM 10 $ uniformM g :: IO [Word8]
[209,138,126,150,165,15,69,203,155,146]

There're special functions for generation of Doubles and @Float in unit interval: uniformDouble01M, uniformDoublePositive01M, uniformFloat01M, uniformFloatPositive01M:

>>> uniformDouble01M =<< create
0.5248103628705498
>>> uniformFloat01M =<< create
0.5248104

For normal distribution and others see modules System.Random.MWC.Distributions and System.Random.MWC.CondensedTable. Note that they could be used with any other generator implementing StatefulGen API

There're special cases for generating random vectors and bytestrings. For example in order to generate random 10-byte sequences as unboxed vector or bytestring:

>>> g <- create
>>> uniformVector g 10 :: IO (U.Vector Word8)
[209,138,126,150,165,15,69,203,155,146]

>>> import qualified Data.ByteString as BS
>>> g <- create
>>> BS.unpack <$> uniformByteStringM 10 g
[138,242,130,33,209,248,89,134,150,180]

Note that uniformByteStringM produces different result from uniformVector since it uses PRNG's output more efficently.

State handling

For repeatability, the state of the generator can be snapshotted and replayed using the save and restore functions. Following example shows how to save and restore generator:

>>> g <- create
>>> replicateM_ 10 (uniformM g :: IO Word64)
>>> s <- save g
>>> uniformM g :: IO Word32
1771812561
>>> uniformM =<< restore s :: IO Word32
1771812561

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