splitmix-0.1.0.3: Fast Splittable PRNG

Safe Haskell | Trustworthy
Language | Haskell2010

System.Random.SplitMix

Contents

- Generation
- Initialisation

Description

SplitMix is a splittable pseudorandom number generator (PRNG) that is quite fast.

Guy L. Steele, Jr., Doug Lea, and Christine H. Flood. 2014. Fast splittable pseudorandom number generators. In Proceedings of the 2014 ACM International Conference on Object Oriented Programming Systems Languages & Applications (OOPSLA '14). ACM, New York, NY, USA, 453-472. DOI: https://doi.org/10.1145/2660193.2660195

The paper describes a new algorithm SplitMix for splittable pseudorandom number generator that is quite fast: 9 64 bit arithmetic/logical operations per 64 bits generated.

SplitMix is tested with two standard statistical test suites (DieHarder and TestU01, this implementation only using the former) and it appears to be adequate for "everyday" use, such as Monte Carlo algorithms and randomized data structures where speed is important.

In particular, it should not be used for cryptographic or security applications, because generated sequences of pseudorandom values are too predictable (the mixing functions are easily inverted, and two successive outputs suffice to reconstruct the internal state).

Note: This module supports all GHCs since GHC-7.0.4, but GHC-7.0 and GHC-7.2 have slow implementation, as there are no native `popCount`.

Synopsis

- data SMGen
- nextWord64 :: SMGen -> (Word64, SMGen)
- nextWord32 :: SMGen -> (Word32, SMGen)
- nextTwoWord32 :: SMGen -> (Word32, Word32, SMGen)
- nextInt :: SMGen -> (Int, SMGen)
- nextDouble :: SMGen -> (Double, SMGen)
- nextFloat :: SMGen -> (Float, SMGen)
- nextInteger :: Integer -> Integer -> SMGen -> (Integer, SMGen)
- splitSMGen :: SMGen -> (SMGen, SMGen)
- bitmaskWithRejection32 :: Word32 -> SMGen -> (Word32, SMGen)
- bitmaskWithRejection32' :: Word32 -> SMGen -> (Word32, SMGen)
- bitmaskWithRejection64 :: Word64 -> SMGen -> (Word64, SMGen)
- bitmaskWithRejection64' :: Word64 -> SMGen -> (Word64, SMGen)
- mkSMGen :: Word64 -> SMGen
- initSMGen :: IO SMGen
- newSMGen :: IO SMGen
- seedSMGen :: Word64 -> Word64 -> SMGen
- seedSMGen' :: (Word64, Word64) -> SMGen
- unseedSMGen :: SMGen -> (Word64, Word64)

# Documentation

data SMGen #

SplitMix generator state.

#### Instances

Instances details

Read SMGen # |
    >>> readMaybe "SMGen 1 1" :: Maybe SMGen
    Just (SMGen 1 1)
    >>> readMaybe "SMGen 1 2" :: Maybe SMGen
    Nothing
    >>> readMaybe (show (mkSMGen 42)) :: Maybe SMGen
    Just (SMGen 9297814886316923340 13679457532755275413)
Instance details Defined in System.Random.SplitMix Methods readsPrec :: Int -> ReadS SMGen # readList :: ReadS [SMGen] # readPrec :: ReadPrec SMGen # readListPrec :: ReadPrec [SMGen] #
Show SMGen # |
Instance details Defined in System.Random.SplitMix Methods showsPrec :: Int -> SMGen -> ShowS # show :: SMGen -> String # showList :: [SMGen] -> ShowS #
NFData SMGen # |
Instance details Defined in System.Random.SplitMix Methods rnf :: SMGen -> () #

nextWord64 :: SMGen -> (Word64, SMGen) #

Generate a `Word64`.

    >>> take 3 $ map (printf "%x") $ unfoldr (Just . nextWord64) (mkSMGen 1337) :: [String]
    ["b5c19e300e8b07b3","d600e0e216c0ac76","c54efc3b3cc5af29"]

nextWord32 :: SMGen -> (Word32, SMGen) #

Generate `Word32` by truncating `nextWord64`.

Since: 0.0.3

nextTwoWord32 :: SMGen -> (Word32, Word32, SMGen) #

Generate two `Word32`.

Since: 0.0.3

nextInt :: SMGen -> (Int, SMGen) #

Generate an `Int`.

nextDouble :: SMGen -> (Double, SMGen) #

Generate a `Double` in `[0, 1)` range.

    >>> take 8 $ map (printf "%0.3f") $ unfoldr (Just . nextDouble) (mkSMGen 1337) :: [String]
    ["0.710","0.836","0.771","0.409","0.297","0.527","0.589","0.067"]

nextFloat :: SMGen -> (Float, SMGen) #

Generate a `Float` in `[0, 1)` range.

    >>> take 8 $ map (printf "%0.3f") $ unfoldr (Just . nextFloat) (mkSMGen 1337) :: [String]
    ["0.057","0.089","0.237","0.383","0.680","0.320","0.826","0.007"]

Since: 0.0.3

nextInteger :: Integer -> Integer -> SMGen -> (Integer, SMGen) #

Generate an `Integer` in closed `[x, y]` range.

splitSMGen :: SMGen -> (SMGen, SMGen) #

Split a generator into a two uncorrelated generators.

# Generation

bitmaskWithRejection32 :: Word32 -> SMGen -> (Word32, SMGen) #

Bitmask with rejection method of generating subrange of `Word32`.

`bitmaskWithRejection32 w32` generates random numbers in closed-open range of `[0, w32)`.

Since: 0.0.3

bitmaskWithRejection32' :: Word32 -> SMGen -> (Word32, SMGen) #

Bitmask with rejection method of generating subrange of `Word32`.

`bitmaskWithRejection32' w32` generates random numbers in closed-closed range of `[0, w32]`.

Since: 0.0.4

bitmaskWithRejection64 :: Word64 -> SMGen -> (Word64, SMGen) #

Bitmask with rejection method of generating subrange of `Word64`.

`bitmaskWithRejection64 w64` generates random numbers in closed-open range of `[0, w64)`.

    >>> take 20 $ unfoldr (Just . bitmaskWithRejection64 5) (mkSMGen 1337)
    [3,1,4,1,2,3,1,1,0,3,4,2,3,0,2,3,3,4,1,0]

Since: 0.0.3

bitmaskWithRejection64' :: Word64 -> SMGen -> (Word64, SMGen) #

Bitmask with rejection method of generating subrange of `Word64`.

`bitmaskWithRejection64' w64` generates random numbers in closed-closed range of `[0, w64]`.

    >>> take 20 $ unfoldr (Just . bitmaskWithRejection64' 5) (mkSMGen 1337)
    [3,1,4,1,2,3,1,1,0,3,4,5,2,3,0,2,3,5,3,4]

Since: 0.0.4

# Initialisation

mkSMGen :: Word64 -> SMGen #

Preferred way to deterministically construct `SMGen`.

    >>> mkSMGen 42
    SMGen 9297814886316923340 13679457532755275413

initSMGen :: IO SMGen #

Initialize `SMGen` using entropy available on the system (time, ...)

newSMGen :: IO SMGen #

Derive a new generator instance from the global `SMGen` using `splitSMGen`.

seedSMGen #

Arguments

:: Word64 | seed
-> Word64 | gamma
-> SMGen |

Create `SMGen` using seed and gamma.

    >>> seedSMGen 2 2
    SMGen 2 3

seedSMGen' :: (Word64, Word64) -> SMGen #

Like `seedSMGen` but takes a pair.

unseedSMGen :: SMGen -> (Word64, Word64) #

Extract current state of `SMGen`.