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

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 Source # | Since: 0.15.0.0

Instance details

Defined in System.Random.MWC

Methods

uniformWord32R :: Word32 -> Gen s -> m Word32 Source #

uniformWord64R :: Word64 -> Gen s -> m Word64 Source #

uniformWord8 :: Gen s -> m Word8 Source #

uniformWord16 :: Gen s -> m Word16 Source #

uniformWord32 :: Gen s -> m Word32 Source #

uniformWord64 :: Gen s -> m Word64 Source #

uniformShortByteString :: Int -> Gen s -> m ShortByteString Source #

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

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

Since: 0.15.0.0

createSystemRandom :: IO GenIO Source #

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

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

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

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

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

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

# Variates: uniformly distributed values

class Uniform a where Source #

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

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

There is a default implementation via `Generic`:

    >>> :set -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 Source #

#### Instances

Instances details

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

class UniformRange a where Source #

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

Since: random-1.2.0

Methods

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

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)

Since: random-1.2.0

#### Instances

Instances details

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

class Variate a where Source #

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

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

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

uniformVector :: (PrimMonad m, StatefulGen g m, Uniform a, Vector v a) => g -> 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

data Seed Source #

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

#### Instances

Instances details

Show Seed Source # |
Instance details Defined in System.Random.MWC Methods showsPrec :: Int -> Seed -> ShowS Source # show :: Seed -> String Source # showList :: [Seed] -> ShowS Source #
Eq Seed Source # |
Instance details Defined in System.Random.MWC Methods (==) :: Seed -> Seed -> Bool Source # (/=) :: Seed -> Seed -> Bool Source #
PrimMonad m => FrozenGen Seed m Source # | 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 Source #

thawGen :: Seed -> m (MutableGen Seed m) Source #

type MutableGen Seed m Source # |
Instance details Defined in System.Random.MWC type MutableGen Seed m = Gen (PrimState m)

fromSeed :: Seed -> Vector Word32 Source #

Convert seed into vector.

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

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

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

# Deprecated

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

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