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

Copyright | (c) 2009-2012 Bryan O'Sullivan
License | BSD3
Maintainer | bos@serpentine.com
Stability | experimental
Portability | portable
Safe Haskell | None
Language | Haskell2010

System.Random.MWC

Contents

- Gen: Pseudo-Random Number Generators
  - Type helpers
- Variates: uniformly distributed values
- Seed: state management
- Deprecated
- References

Description

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 are 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 Data.Int
    >>> import qualified Data.Vector.Unboxed as U
    >>> import System.Random.Stateful
    >>> g <- initialize $ U.fromList [1,2,3]
    >>> uniformRM (1,200) g :: IO Int64
    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 are 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 efficiently.

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

Synopsis

- data Gen s
- create :: PrimMonad m => m (Gen (PrimState m))
- initialize :: (PrimMonad m, Vector v Word32) => v Word32 -> m (Gen (PrimState m))
- createSystemSeed :: IO Seed
- createSystemRandom :: IO GenIO
- withSystemRandomST :: (forall s. Gen s -> ST s a) -> IO a
- type GenIO = Gen (PrimState IO)
- type GenST s = Gen (PrimState (ST s))
- asGenIO :: (GenIO -> IO a) -> GenIO -> IO a
- asGenST :: (GenST s -> ST s a) -> GenST s -> ST s a
- class Uniform a where
  - uniformM :: StatefulGen g m => g -> m a
- class UniformRange a where
  - uniformRM :: StatefulGen g m => (a, a) -> g -> m a
  - isInRange :: (a, a) -> a -> Bool
- class Variate a where
  - uniform :: PrimMonad m => Gen (PrimState m) -> m a
  - uniformR :: PrimMonad m => (a, a) -> Gen (PrimState m) -> m a
- uniformVector :: (PrimMonad m, StatefulGen g m, Uniform a, Vector v a) => g -> 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))
- withSystemRandom :: PrimBase m => (Gen (PrimState m) -> m a) -> IO a

# Gen: Pseudo-Random Number Generators

data Gen s #

State of the pseudo-random number generator. It uses mutable state so same generator shouldn't be used from the different threads simultaneously.

#### Instances

Instances details

(s ~ PrimState m, PrimMonad m) => StatefulGen (Gen s) m # | Since: 0.15.0.0
Instance details Defined in System.Random.MWC Methods uniformWord32R :: Word32 -> Gen s -> m Word32 # uniformWord64R :: Word64 -> Gen s -> m Word64 # uniformWord8 :: Gen s -> m Word8 # uniformWord16 :: Gen s -> m Word16 # uniformWord32 :: Gen s -> m Word32 # uniformWord64 :: Gen s -> m Word64 # uniformByteArrayM :: Bool -> Int -> Gen s -> m ByteArray # uniformShortByteString :: Int -> Gen s -> m ShortByteString #

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

Create a generator for variates using a fixed seed.

initialize :: (PrimMonad m, Vector v Word32) => v Word32 -> m (Gen (PrimState m)) #

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 (fromList [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

In the MWC algorithm, the carry value must be strictly smaller than the multiplicator (see https://en.wikipedia.org/wiki/Multiply-with-carry). Hence, if a seed contains exactly 258 elements, the carry value, which is the last of the 258 values, is moduloed by the multiplicator.

Note that if the first carry value is strictly smaller than the multiplicator, all subsequent carry values are also strictly smaller than the multiplicator (a proof of this is in the comments of the code of `uniformWord32`), hence when restoring a saved state, we have the guarantee that moduloing the saved carry won't modify its value.

createSystemSeed :: IO Seed #

Generate random seed for generator using system's fast source of pseudo-random numbers.

Since: 0.15.0.0

createSystemRandom :: IO GenIO #

Seed a PRNG with data from the system's fast source of pseudo-random numbers.

withSystemRandomST :: (forall s. Gen s -> ST s a) -> IO a #

Seed PRNG with data from the system's fast source of pseudo-random numbers and execute computation in ST monad.

Since: 0.15.0.0

## Type helpers

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.

type GenIO = Gen (PrimState IO) #

A shorter name for PRNG state in the `IO` monad.

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

A shorter name for PRNG state in the `ST` monad.

asGenIO :: (GenIO -> IO a) -> GenIO -> IO a #

Constrain the type of an action to run in the `IO` monad.

asGenST :: (GenST s -> ST s a) -> GenST s -> ST s a #

Constrain the type of an action to run in the `ST` monad.

# Variates: uniformly distributed values

class Uniform a where #

The class of types for which a uniformly distributed value can be drawn from all possible values of the type.

Since: random-1.2.0

Minimal complete definition

Nothing

Methods

uniformM :: StatefulGen g m => g -> m a #

Generates a value uniformly distributed over all possible values of that type.

There is a default implementation via `Generic`:

    >>> :seti -XDeriveGeneric -XDeriveAnyClass
    >>> import GHC.Generics (Generic)
    >>> import System.Random.Stateful
    >>> data MyBool = MyTrue | MyFalse deriving (Show, Generic, Finite, Uniform)
    >>> data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Show, Generic, Finite, Uniform)
    >>> gen <- newIOGenM (mkStdGen 42)
    >>> uniformListM 10 gen :: IO [Action]
    [Code MyTrue,Code MyTrue,Eat Nothing,Code MyFalse,Eat (Just False),Eat (Just True),Eat Nothing,Eat (Just False),Sleep,Code MyFalse]

Since: random-1.2.0

default uniformM :: (StatefulGen g m, Generic a, GUniform (Rep a)) => g -> m a #

#### Instances

Instances details

Uniform CBool |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CBool #
Uniform CChar |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CChar #
Uniform CInt |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CInt #
Uniform CIntMax |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CIntMax #
Uniform CIntPtr |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CIntPtr #
Uniform CLLong |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CLLong #
Uniform CLong |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CLong #
Uniform CPtrdiff |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CPtrdiff #
Uniform CSChar |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CSChar #
Uniform CShort |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CShort #
Uniform CSigAtomic |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CSigAtomic #
Uniform CSize |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CSize #
Uniform CUChar |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUChar #
Uniform CUInt |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUInt #
Uniform CUIntMax |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUIntMax #
Uniform CUIntPtr |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUIntPtr #
Uniform CULLong |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CULLong #
Uniform CULong |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CULong #
Uniform CUShort |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUShort #
Uniform CWchar |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CWchar #
Uniform Int16 |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int16 #
Uniform Int32 |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int32 #
Uniform Int64 |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int64 #
Uniform Int8 |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int8 #
Uniform Word16 |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word16 #
Uniform Word32 |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word32 #
Uniform Word64 |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word64 #
Uniform Word8 |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word8 #
Uniform () |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m () #
Uniform Bool |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Bool #
Uniform Char |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Char #
Uniform Int |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int #
Uniform Word |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word #
(Finite a, Uniform a) => Uniform (Maybe a) |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (Maybe a) #
(Finite a, Uniform a, Finite b, Uniform b) => Uniform (Either a b) |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (Either a b) #
(Uniform a, Uniform b) => Uniform (a, b) |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b) #
(Uniform a, Uniform b, Uniform c) => Uniform (a, b, c) |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c) #
(Uniform a, Uniform b, Uniform c, Uniform d) => Uniform (a, b, c, d) |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c, d) #
(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e) => Uniform (a, b, c, d, e) |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c, d, e) #
(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f) => Uniform (a, b, c, d, e, f) |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c, d, e, f) #
(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f, Uniform g) => Uniform (a, b, c, d, e, f, g) |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g0 m => g0 -> m (a, b, c, d, e, f, g) #

class UniformRange a where #

The class of types for which a uniformly distributed value can be drawn from a range.

Since: random-1.2.0

Minimal complete definition

Nothing

Methods

uniformRM :: StatefulGen g m => (a, a) -> g -> m a #

Generates a value uniformly distributed over the provided range, which is interpreted as inclusive in the lower and upper bound.

- `uniformRM (1 :: Int, 4 :: Int)` generates values uniformly from the set \(\{1,2,3,4\}\)
- `uniformRM (1 :: Float, 4 :: Float)` generates values uniformly from the set \(\{x\;|\;1 \le x \le 4\}\)

The following law should hold to make the function always defined:

    uniformRM (a, b) = uniformRM (b, a)

The range is understood as defined by means of `isInRange`, so

    isInRange (a, b) <$> uniformRM (a, b) gen == pure True

but beware of floating point number caveats.

There is a default implementation via `Generic`:

    >>> :seti -XDeriveGeneric -XDeriveAnyClass
    >>> import GHC.Generics (Generic)
    >>> import Data.Word (Word8)
    >>> import Control.Monad (replicateM)
    >>> import System.Random.Stateful
    >>> gen <- newIOGenM (mkStdGen 42)
    >>> data Tuple = Tuple Bool Word8 deriving (Show, Generic, UniformRange)
    >>> replicateM 10 (uniformRM (Tuple False 100, Tuple True 150) gen)
    [Tuple False 102,Tuple True 118,Tuple False 115,Tuple True 113,Tuple True 126,Tuple False 127,Tuple True 130,Tuple False 113,Tuple False 150,Tuple False 125]

Since: random-1.2.0

default uniformRM :: (StatefulGen g m, Generic a, GUniformRange (Rep a)) => (a, a) -> g -> m a #

isInRange :: (a, a) -> a -> Bool #

A notion of (inclusive) ranges prescribed to `a`.

Ranges are symmetric:

    isInRange (lo, hi) x == isInRange (hi, lo) x

Ranges include their endpoints:

    isInRange (lo, hi) lo == True

When endpoints coincide, there is nothing else:

    isInRange (x, x) y == x == y

Endpoints are endpoints:

    isInRange (lo, hi) x ==>
    isInRange (lo, x) hi == x == hi

Ranges are transitive relations:

    isInRange (lo, hi) lo' && isInRange (lo, hi) hi' && isInRange (lo', hi') x
    ==> isInRange (lo, hi) x

There is a default implementation of `isInRange` via `Generic`. Other helper function that can be used for implementing this function are `isInRangeOrd` and `isInRangeEnum`

Since: random-1.3.0

default isInRange :: (Generic a, GUniformRange (Rep a)) => (a, a) -> a -> Bool #

#### Instances

Instances details

UniformRange CBool |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CBool, CBool) -> g -> m CBool # isInRange :: (CBool, CBool) -> CBool -> Bool #
UniformRange CChar |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CChar, CChar) -> g -> m CChar # isInRange :: (CChar, CChar) -> CChar -> Bool #
UniformRange CDouble | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CDouble, CDouble) -> g -> m CDouble # isInRange :: (CDouble, CDouble) -> CDouble -> Bool #
UniformRange CFloat | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CFloat, CFloat) -> g -> m CFloat # isInRange :: (CFloat, CFloat) -> CFloat -> Bool #
UniformRange CInt |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CInt, CInt) -> g -> m CInt # isInRange :: (CInt, CInt) -> CInt -> Bool #
UniformRange CIntMax |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CIntMax, CIntMax) -> g -> m CIntMax # isInRange :: (CIntMax, CIntMax) -> CIntMax -> Bool #
UniformRange CIntPtr |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CIntPtr, CIntPtr) -> g -> m CIntPtr # isInRange :: (CIntPtr, CIntPtr) -> CIntPtr -> Bool #
UniformRange CLLong |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CLLong, CLLong) -> g -> m CLLong # isInRange :: (CLLong, CLLong) -> CLLong -> Bool #
UniformRange CLong |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CLong, CLong) -> g -> m CLong # isInRange :: (CLong, CLong) -> CLong -> Bool #
UniformRange CPtrdiff |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CPtrdiff, CPtrdiff) -> g -> m CPtrdiff # isInRange :: (CPtrdiff, CPtrdiff) -> CPtrdiff -> Bool #
UniformRange CSChar |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CSChar, CSChar) -> g -> m CSChar # isInRange :: (CSChar, CSChar) -> CSChar -> Bool #
UniformRange CShort |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CShort, CShort) -> g -> m CShort # isInRange :: (CShort, CShort) -> CShort -> Bool #
UniformRange CSigAtomic |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CSigAtomic, CSigAtomic) -> g -> m CSigAtomic # isInRange :: (CSigAtomic, CSigAtomic) -> CSigAtomic -> Bool #
UniformRange CSize |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CSize, CSize) -> g -> m CSize # isInRange :: (CSize, CSize) -> CSize -> Bool #
UniformRange CUChar |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUChar, CUChar) -> g -> m CUChar # isInRange :: (CUChar, CUChar) -> CUChar -> Bool #
UniformRange CUInt |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUInt, CUInt) -> g -> m CUInt # isInRange :: (CUInt, CUInt) -> CUInt -> Bool #
UniformRange CUIntMax |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUIntMax, CUIntMax) -> g -> m CUIntMax # isInRange :: (CUIntMax, CUIntMax) -> CUIntMax -> Bool #
UniformRange CUIntPtr |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUIntPtr, CUIntPtr) -> g -> m CUIntPtr # isInRange :: (CUIntPtr, CUIntPtr) -> CUIntPtr -> Bool #
UniformRange CULLong |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CULLong, CULLong) -> g -> m CULLong # isInRange :: (CULLong, CULLong) -> CULLong -> Bool #
UniformRange CULong |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CULong, CULong) -> g -> m CULong # isInRange :: (CULong, CULong) -> CULong -> Bool #
UniformRange CUShort |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUShort, CUShort) -> g -> m CUShort # isInRange :: (CUShort, CUShort) -> CUShort -> Bool #
UniformRange CWchar |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CWchar, CWchar) -> g -> m CWchar # isInRange :: (CWchar, CWchar) -> CWchar -> Bool #
UniformRange Int16 |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int16, Int16) -> g -> m Int16 # isInRange :: (Int16, Int16) -> Int16 -> Bool #
UniformRange Int32 |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int32, Int32) -> g -> m Int32 # isInRange :: (Int32, Int32) -> Int32 -> Bool #
UniformRange Int64 |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int64, Int64) -> g -> m Int64 # isInRange :: (Int64, Int64) -> Int64 -> Bool #
UniformRange Int8 |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int8, Int8) -> g -> m Int8 # isInRange :: (Int8, Int8) -> Int8 -> Bool #
UniformRange Word16 |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word16, Word16) -> g -> m Word16 # isInRange :: (Word16, Word16) -> Word16 -> Bool #
UniformRange Word32 |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word32, Word32) -> g -> m Word32 # isInRange :: (Word32, Word32) -> Word32 -> Bool #
UniformRange Word64 |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word64, Word64) -> g -> m Word64 # isInRange :: (Word64, Word64) -> Word64 -> Bool #
UniformRange Word8 |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word8, Word8) -> g -> m Word8 # isInRange :: (Word8, Word8) -> Word8 -> Bool #
UniformRange Integer |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Integer, Integer) -> g -> m Integer # isInRange :: (Integer, Integer) -> Integer -> Bool #
UniformRange Natural |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Natural, Natural) -> g -> m Natural # isInRange :: (Natural, Natural) -> Natural -> Bool #
UniformRange () |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((), ()) -> g -> m () # isInRange :: ((), ()) -> () -> Bool #
UniformRange Bool |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Bool, Bool) -> g -> m Bool # isInRange :: (Bool, Bool) -> Bool -> Bool #
UniformRange Char |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Char, Char) -> g -> m Char # isInRange :: (Char, Char) -> Char -> Bool #
UniformRange Double | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Double, Double) -> g -> m Double # isInRange :: (Double, Double) -> Double -> Bool #
UniformRange Float | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Float, Float) -> g -> m Float # isInRange :: (Float, Float) -> Float -> Bool #
UniformRange Int |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int, Int) -> g -> m Int # isInRange :: (Int, Int) -> Int -> Bool #
UniformRange Word |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word, Word) -> g -> m Word # isInRange :: (Word, Word) -> Word -> Bool #
(UniformRange a, UniformRange b) => UniformRange (a, b) |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b), (a, b)) -> g -> m (a, b) # isInRange :: ((a, b), (a, b)) -> (a, b) -> Bool #
(UniformRange a, UniformRange b, UniformRange c) => UniformRange (a, b, c) |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c), (a, b, c)) -> g -> m (a, b, c) # isInRange :: ((a, b, c), (a, b, c)) -> (a, b, c) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d) => UniformRange (a, b, c, d) |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c, d), (a, b, c, d)) -> g -> m (a, b, c, d) # isInRange :: ((a, b, c, d), (a, b, c, d)) -> (a, b, c, d) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e) => UniformRange (a, b, c, d, e) |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c, d, e), (a, b, c, d, e)) -> g -> m (a, b, c, d, e) # isInRange :: ((a, b, c, d, e), (a, b, c, d, e)) -> (a, b, c, d, e) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f) => UniformRange (a, b, c, d, e, f) |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> g -> m (a, b, c, d, e, f) # isInRange :: ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> (a, b, c, d, e, f) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f, UniformRange g) => UniformRange (a, b, c, d, e, f, g) |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g0 m => ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> g0 -> m (a, b, c, d, e, f, g) # isInRange :: ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> (a, b, c, d, e, f, g) -> Bool #

class Variate a where #

NOTE: Consider use of more principled type classes `Uniform` and `UniformRange` instead.

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 a #

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 a #

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.

#### Instances

Instances details

Variate Int16 # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Int16 # uniformR :: PrimMonad m => (Int16, Int16) -> Gen (PrimState m) -> m Int16 #
Variate Int32 # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Int32 # uniformR :: PrimMonad m => (Int32, Int32) -> Gen (PrimState m) -> m Int32 #
Variate Int64 # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Int64 # uniformR :: PrimMonad m => (Int64, Int64) -> Gen (PrimState m) -> m Int64 #
Variate Int8 # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Int8 # uniformR :: PrimMonad m => (Int8, Int8) -> Gen (PrimState m) -> m Int8 #
Variate Word16 # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Word16 # uniformR :: PrimMonad m => (Word16, Word16) -> Gen (PrimState m) -> m Word16 #
Variate Word32 # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Word32 # uniformR :: PrimMonad m => (Word32, Word32) -> Gen (PrimState m) -> m Word32 #
Variate Word64 # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Word64 # uniformR :: PrimMonad m => (Word64, Word64) -> Gen (PrimState m) -> m Word64 #
Variate Word8 # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Word8 # uniformR :: PrimMonad m => (Word8, Word8) -> Gen (PrimState m) -> m Word8 #
Variate Bool # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Bool # uniformR :: PrimMonad m => (Bool, Bool) -> Gen (PrimState m) -> m Bool #
Variate Double # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Double # uniformR :: PrimMonad m => (Double, Double) -> Gen (PrimState m) -> m Double #
Variate Float # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Float # uniformR :: PrimMonad m => (Float, Float) -> Gen (PrimState m) -> m Float #
Variate Int # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Int # uniformR :: PrimMonad m => (Int, Int) -> Gen (PrimState m) -> m Int #
Variate Word # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m Word # uniformR :: PrimMonad m => (Word, Word) -> Gen (PrimState m) -> m Word #
(Variate a, Variate b) => Variate (a, b) # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m (a, b) # uniformR :: PrimMonad m => ((a, b), (a, b)) -> Gen (PrimState m) -> m (a, b) #
(Variate a, Variate b, Variate c) => Variate (a, b, c) # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m (a, b, c) # uniformR :: PrimMonad m => ((a, b, c), (a, b, c)) -> Gen (PrimState m) -> m (a, b, c) #
(Variate a, Variate b, Variate c, Variate d) => Variate (a, b, c, d) # |
Instance details Defined in System.Random.MWC Methods uniform :: PrimMonad m => Gen (PrimState m) -> m (a, b, c, d) # uniformR :: PrimMonad m => ((a, b, c, d), (a, b, c, d)) -> Gen (PrimState m) -> m (a, b, c, d) #

uniformVector :: (PrimMonad m, StatefulGen g m, Uniform a, Vector v a) => g -> Int -> m (v a) #

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

data Seed #

An immutable snapshot of the state of a `Gen`.

#### Instances

Instances details

Show Seed # |
Instance details Defined in System.Random.MWC Methods showsPrec :: Int -> Seed -> ShowS # show :: Seed -> String # showList :: [Seed] -> ShowS #
Eq Seed # |
Instance details Defined in System.Random.MWC Methods (==) :: Seed -> Seed -> Bool # (/=) :: Seed -> Seed -> Bool #
SeedGen Seed # |
Instance details Defined in System.Random.MWC Associated Types
type SeedSize Seed |
Instance details Defined in System.Random.MWC type SeedSize Seed = 1032
Methods fromSeed :: Seed Seed -> Seed # toSeed :: Seed -> Seed Seed # fromSeed64 :: NonEmpty Word64 -> Seed # toSeed64 :: Seed -> NonEmpty Word64 #
PrimMonad m => FrozenGen Seed m # | Since: 0.15.0.0
Instance details Defined in System.Random.MWC Associated Types
type MutableGen Seed m |
Instance details Defined in System.Random.MWC type MutableGen Seed m = Gen (PrimState m)
Methods freezeGen :: MutableGen Seed m -> m Seed # modifyGen :: MutableGen Seed m -> (Seed -> (a, Seed)) -> m a # overwriteGen :: MutableGen Seed m -> Seed -> m () #
PrimMonad m => ThawedGen Seed m # |
Instance details Defined in System.Random.MWC Methods thawGen :: Seed -> m (MutableGen Seed m) #
type SeedSize Seed # |
Instance details Defined in System.Random.MWC type SeedSize Seed = 1032
type MutableGen Seed m # |
Instance details Defined in System.Random.MWC type MutableGen Seed m = Gen (PrimState m)

fromSeed :: Seed -> Vector Word32 #

Convert seed into vector.

toSeed :: Vector v Word32 => v Word32 -> Seed #

Convert vector to `Seed`. It acts similarly 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

save :: PrimMonad m => Gen (PrimState m) -> m Seed #

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

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

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

# Deprecated

withSystemRandom :: PrimBase m => (Gen (PrimState m) -> m a) -> IO a #

Deprecated: Use withSystemRandomST or createSystemSeed or createSystemRandom instead

Seed a PRNG with data from the system's fast source of pseudo-random numbers, then run the given action.

This function is unsafe and for example allows STRefs or any other mutable data structure to escape scope:

    >>> ref <- withSystemRandom $ \_ -> newSTRef 1
    >>> withSystemRandom $ \_ -> modifySTRef ref succ >> readSTRef ref
    2
    >>> withSystemRandom $ \_ -> modifySTRef ref succ >> readSTRef ref
    3

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