mwc-random-0.7.0.1: Fast, high quality pseudo random number generation

Portabilityportable
Stabilityexperimental
Maintainerbos@serpentine.com

System.Random.MWC

Contents

Description

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

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.

Synopsis

Types

data Gen s Source

State of the pseudo-random number generator.

type GenIO = Gen (PrimState IO)Source

A shorter name for PRNG state in the IO monad.

type GenST s = Gen (PrimState (ST s))Source

A shorter name for PRNG state in the ST monad.

data Seed Source

An immutable snapshot of the state of a Gen.

Instances

class Unbox a => Variate a whereSource

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.

Methods

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

Instances

Other distributions

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

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

Create a generator for variates using a fixed seed.

initialize :: PrimMonad m => Vector 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 (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 xored against elements of the default seed until 256 elements are reached.

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.

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

save :: PrimMonad m => Gen (PrimState m) -> m SeedSource

Save the state of a Gen, for later use by restore.

restore :: PrimMonad m => Seed -> m (Gen (PrimState m))Source

Create a new Gen that mirrors the state of a saved Seed.

Helper functions

uniformVector :: (PrimMonad m, Variate a) => Gen (PrimState m) -> Int -> m (Vector 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.

References