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

Stability | experimental |

Maintainer | bos@serpentine.com |

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
`System.Random.MWC.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:

- Using the
`withSystemRandom`

call, which creates a random state. - Supply your own seed to
`initialize`

function. - 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 (uniformVector 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

Keep this generator and use it wherever random values are required. Get a random
value using `uniform`

or `uniformR`

:

v <- uniform gen

v <- uniformR (1, 52) gen

- data Gen s
- type GenIO = Gen (PrimState IO)
- type GenST s = Gen (PrimState (ST s))
- create :: PrimMonad m => m (Gen (PrimState m))
- initialize :: (PrimMonad m, Vector v Word32) => v Word32 -> m (Gen (PrimState m))
- withSystemRandom :: PrimMonad m => (Gen (PrimState m) -> m a) -> IO a
- class Variate a where
- uniformVector :: (PrimMonad m, Variate a, Vector v a) => Gen (PrimState m) -> Int -> m (v a)
- data Seed
- fromSeed :: Seed -> Vector Word32
- toSeed :: Vector v Word32 => v Word32 -> Seed
- save :: PrimMonad m => Gen (PrimState m) -> m Seed
- restore :: PrimMonad m => Seed -> m (Gen (PrimState m))

# Gen: Pseudo-Random Number Generators

create :: PrimMonad m => m (Gen (PrimState m))Source

Create a generator for variates using a fixed seed.

initialize :: (PrimMonad m, Vector v Word32) => v Word32 -> m (Gen (PrimState m))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 (singleton 42)

initialize (toList [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.

If a seed contains exactly 258 elements, then the last two elements
are used to set the generator's initial state. This allows for
complete generator reproducibility, so that e.g. `gen' == gen`

in
the following example:

gen' <-`initialize`

.`fromSeed`

=<<`save`

withSystemRandom :: PrimMonad m => (Gen (PrimState m) -> m 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.

This is a heavyweight function, intended to be called only
occasionally (e.g. once per thread). You should use the `Gen`

it
creates to generate many random numbers.

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

# Variates: uniformly distributed values

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 :: PrimMonad m => Gen (PrimState m) -> m 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).

To generate a `Float`

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

variates, subtract
2**(-53).

uniformR :: PrimMonad m => (a, a) -> Gen (PrimState m) -> m aSource

Generate single uniformly distributed random variable in a given range.

- For integral types inclusive range is used.
- For floating point numbers range (a,b] is used if one ignores rounding errors.

Variate Bool | |

Variate Double | |

Variate Float | |

Variate Int | |

Variate Int8 | |

Variate Int16 | |

Variate Int32 | |

Variate Int64 | |

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

uniformVector :: (PrimMonad m, Variate a, Vector v a) => Gen (PrimState m) -> Int -> m (v a)Source

Generate a vector 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.

# Seed: state management

toSeed :: Vector v Word32 => v Word32 -> SeedSource

Convert vector to `Seed`

. It acts similarily to `initialize`

and
will accept any vector. If you want to pass seed immediately to
restore you better call initialize directly since following law holds:

restore (toSeed v) = initialize v

# References

- 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