Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The seeds generated by split are not independent #25

Closed
idontgetoutmuch opened this issue Mar 29, 2015 · 27 comments · Fixed by #61 or #62
Closed

The seeds generated by split are not independent #25

idontgetoutmuch opened this issue Mar 29, 2015 · 27 comments · Fixed by #61 or #62
Milestone

Comments

@idontgetoutmuch
Copy link
Member

See - https://ghc.haskell.org/trac/ghc/ticket/3620 (and also https://ghc.haskell.org/trac/ghc/ticket/3575) I just ran the example https://ghc.haskell.org/trac/ghc/attachment/ticket/3620/RandomnessTest2.hs and got

Generated 2000 pairs of numbers from 0 to 1 -- 1299 pairs contained equal numbers and we expected about 1000.
Generated 3000 pairs of numbers from 0 to 2 -- 187 pairs contained equal numbers and we expected about 1000.
Generated 4000 pairs of numbers from 0 to 3 -- 101 pairs contained equal numbers and we expected about 1000.
Generated 5000 pairs of numbers from 0 to 4 -- 271 pairs contained equal numbers and we expected about 1000.
Generated 6000 pairs of numbers from 0 to 5 -- 359 pairs contained equal numbers and we expected about 1000.
Generated 7000 pairs of numbers from 0 to 6 -- 1401 pairs contained equal numbers and we expected about 1000.
Generated 8000 pairs of numbers from 0 to 7 -- 158 pairs contained equal numbers and we expected about 1000.
Generated 9000 pairs of numbers from 0 to 8 -- 53 pairs contained equal numbers and we expected about 1000.
Generated 10000 pairs of numbers from 0 to 9 -- 535 pairs contained equal numbers and we expected about 1000.
Generated 11000 pairs of numbers from 0 to 10 -- 0 pairs contained equal numbers and we expected about 1000.
Generated 12000 pairs of numbers from 0 to 11 -- 70 pairs contained equal numbers and we expected about 1000.
Generated 13000 pairs of numbers from 0 to 12 -- 0 pairs contained equal numbers and we expected about 1000.
Generated 14000 pairs of numbers from 0 to 13 -- 0 pairs contained equal numbers and we expected about 1000.
Generated 15000 pairs of numbers from 0 to 14 -- 783 pairs contained equal numbers and we expected about 1000.

On the other hand the example from http://publications.lib.chalmers.se/records/fulltext/183348/local_183348.pdf now seems to work

> quickCheckWith stdArgs { maxSuccess = 10000 } prop_shouldFail
*** Failed! Falsifiable (after 2 tests): 
((),Int14 13)
Int14 13
@idontgetoutmuch
Copy link
Member Author

I just tried the same test but using https://hackage.haskell.org/package/tf-random

module Main where

import Control.Monad
import System.Random.TF.Gen
import System.Random.TF.Instances

splitN :: (RandomGen g) => Int -> g -> ([g], g)
splitN 0 g = ([], g)
splitN n g = (g1:l, g')
  where
  (l, g') = splitN (n-1) g2
  (g1, g2) = split g

-- The funny splitting operation.
split' :: (RandomGen g) => g -> (g, g)
split' g = (g12, g21)
  where
  (g1, g2) = split g
  (_, g12) = split g1
  (g21, _) = split g2

-- This test checks if generators created by calling split 2 times are independent.
-- It generates pairs of integers from 0 to n-1, using split' to
-- generate both numbers using one seed. Then it counts how often the
-- two numbers are equal.
test :: (RandomGen g) => Int -> Int -> g -> Int
test numTests n g = equals
  where
  (gs, _) = splitN numTests g
  equals = count id $ map single gs
  count p l = length $ filter p l
  single g' = (fst $ randomR (0, n-1) g1) == (fst $ randomR (0, n-1) g2)
    where
    (g1, g2) = split' g'

main = do
  let g = seedTFGen (42, 42, 42, 42)
  forM_ [2..15] $ \i -> do
    let actual = test (i * 1000) i g
    putStrLn $ "Generated " ++ show (i * 1000)
      ++ " pairs of numbers from 0 to " ++ show (i - 1)
      ++ " -- " ++ show actual ++ " pairs contained equal numbers "
      ++ "and we expected about 1000."

and this gives what seems to be a correct result

Generated 2000 pairs of numbers from 0 to 1 -- 1013 pairs contained equal numbers and we expected about 1000.
Generated 3000 pairs of numbers from 0 to 2 -- 977 pairs contained equal numbers and we expected about 1000.
Generated 4000 pairs of numbers from 0 to 3 -- 1016 pairs contained equal numbers and we expected about 1000.
Generated 5000 pairs of numbers from 0 to 4 -- 996 pairs contained equal numbers and we expected about 1000.
Generated 6000 pairs of numbers from 0 to 5 -- 988 pairs contained equal numbers and we expected about 1000.
Generated 7000 pairs of numbers from 0 to 6 -- 967 pairs contained equal numbers and we expected about 1000.
Generated 8000 pairs of numbers from 0 to 7 -- 976 pairs contained equal numbers and we expected about 1000.
Generated 9000 pairs of numbers from 0 to 8 -- 975 pairs contained equal numbers and we expected about 1000.
Generated 10000 pairs of numbers from 0 to 9 -- 992 pairs contained equal numbers and we expected about 1000.
Generated 11000 pairs of numbers from 0 to 10 -- 986 pairs contained equal numbers and we expected about 1000.
Generated 12000 pairs of numbers from 0 to 11 -- 991 pairs contained equal numbers and we expected about 1000.
Generated 13000 pairs of numbers from 0 to 12 -- 973 pairs contained equal numbers and we expected about 1000.
Generated 14000 pairs of numbers from 0 to 13 -- 990 pairs contained equal numbers and we expected about 1000.
Generated 15000 pairs of numbers from 0 to 14 -- 996 pairs contained equal numbers and we expected about 1000.

@idontgetoutmuch
Copy link
Member Author

Here's the example from http://kenta.blogspot.co.nz/2014/02/rzzllapd-nonrandomness-of-first-random.html (slightly modified to use the histogram-fill package)

{-# OPTIONS_GHC -Wall                      #-}
{-# OPTIONS_GHC -fno-warn-name-shadowing   #-}
{-# OPTIONS_GHC -fno-warn-type-defaults    #-}
{-# OPTIONS_GHC -fno-warn-unused-do-bind   #-}
{-# OPTIONS_GHC -fno-warn-missing-methods  #-}
{-# OPTIONS_GHC -fno-warn-orphans          #-}

module Main where

import System.Random (StdGen, mkStdGen, randomR);

import qualified Data.Vector.Unboxed as V
import Data.Histogram ( asList )
import Data.Histogram.Fill
import Data.Histogram.Generic ( Histogram )

rollDice :: StdGen -> (Int, StdGen)
rollDice = randomR (1,6)

get_first :: Int -> Int
get_first seed = fst $ rollDice $ mkStdGen seed

hb :: HBuilder Int (Histogram V.Vector BinI Int)
hb = forceInt -<< mkSimple (binI 1 6)

hist :: Histogram V.Vector BinI Int
hist = fillBuilder hb (map get_first [0..53667])

main :: IO ()
main = mapM_ print $ asList hist
*Main> main
(1,0)
(2,0)
(3,0)
(4,0)
(5,0)
(6,53668)

Not really very random, Dilbert notwithstanding: http://dilbert.com/strip/2001-10-25.

@cartazio
Copy link
Contributor

Sounds like weve got some work to do
On Mar 29, 2015 10:53 AM, "idontgetoutmuch" [email protected]
wrote:

Here's the example from
http://kenta.blogspot.co.nz/2014/02/rzzllapd-nonrandomness-of-first-random.html
(slightly modified to use the histogram-fill package)

{-# OPTIONS_GHC -Wall #-}
{-# OPTIONS_GHC -fno-warn-name-shadowing #-}
{-# OPTIONS_GHC -fno-warn-type-defaults #-}
{-# OPTIONS_GHC -fno-warn-unused-do-bind #-}
{-# OPTIONS_GHC -fno-warn-missing-methods #-}
{-# OPTIONS_GHC -fno-warn-orphans #-}

module Main where

import System.Random (StdGen, mkStdGen, randomR);

import qualified Data.Vector.Unboxed as V
import Data.Histogram ( asList )
import Data.Histogram.Fill
import Data.Histogram.Generic ( Histogram )

rollDice :: StdGen -> (Int, StdGen)
rollDice = randomR (1,6)

get_first :: Int -> Int
get_first seed = fst $ rollDice $ mkStdGen seed

hb :: HBuilder Int (Histogram V.Vector BinI Int)
hb = forceInt -<< mkSimple (binI 1 6)

hist :: Histogram V.Vector BinI Int
hist = fillBuilder hb (map get_first [0..53667])

main :: IO ()
main = mapM_ print $ asList hist

*Main> main
(1,0)
(2,0)
(3,0)
(4,0)
(5,0)
(6,53668)

Not really very random, Dilbert notwithstanding:
http://dilbert.com/strip/2001-10-25.


Reply to this email directly or view it on GitHub
#25 (comment).

@cartazio
Copy link
Contributor

I kinda suspected the current splitting design had this sort of problem but
it's good we now have evidence!
On Mar 29, 2015 11:49 AM, "Carter Schonwald" [email protected]
wrote:

Sounds like weve got some work to do
On Mar 29, 2015 10:53 AM, "idontgetoutmuch" [email protected]
wrote:

Here's the example from
http://kenta.blogspot.co.nz/2014/02/rzzllapd-nonrandomness-of-first-random.html
(slightly modified to use the histogram-fill package)

{-# OPTIONS_GHC -Wall #-}
{-# OPTIONS_GHC -fno-warn-name-shadowing #-}
{-# OPTIONS_GHC -fno-warn-type-defaults #-}
{-# OPTIONS_GHC -fno-warn-unused-do-bind #-}
{-# OPTIONS_GHC -fno-warn-missing-methods #-}
{-# OPTIONS_GHC -fno-warn-orphans #-}

module Main where

import System.Random (StdGen, mkStdGen, randomR);

import qualified Data.Vector.Unboxed as V
import Data.Histogram ( asList )
import Data.Histogram.Fill
import Data.Histogram.Generic ( Histogram )

rollDice :: StdGen -> (Int, StdGen)
rollDice = randomR (1,6)

get_first :: Int -> Int
get_first seed = fst $ rollDice $ mkStdGen seed

hb :: HBuilder Int (Histogram V.Vector BinI Int)
hb = forceInt -<< mkSimple (binI 1 6)

hist :: Histogram V.Vector BinI Int
hist = fillBuilder hb (map get_first [0..53667])

main :: IO ()
main = mapM_ print $ asList hist

*Main> main
(1,0)
(2,0)
(3,0)
(4,0)
(5,0)
(6,53668)

Not really very random, Dilbert notwithstanding:
http://dilbert.com/strip/2001-10-25.


Reply to this email directly or view it on GitHub
#25 (comment).

@gbaz
Copy link

gbaz commented Apr 4, 2015

This splitting design has been known to have this problem for the past six years going by those tickets -- I think longer. And the guarantees made by the random library have never suggested otherwise. So I think a better random should have better splitting but I also think that this is not an immediate "must fix" bug, but a property that should inform our selection of a new random algorithm in the coming future.

@cartazio
Copy link
Contributor

cartazio commented Apr 4, 2015

agreed, and i think its worth burning some time on

  1. building some infrastructure to compare different algorithms in both
    quality of randomness AND in performance

  2. exploring preexisting algorithms, and experimenting with new approaches
    informed by preexisting work AND buttressed by having a really good quality
    RNG testing infrastructure that we can be systematic about

On Sat, Apr 4, 2015 at 2:54 PM, gbaz [email protected] wrote:

This splitting design has been known to have this problem for the past six
years going by those tickets -- I think longer. And the guarantees made by
the random library have never suggested otherwise. So I think a better
random should have better splitting but I also think that this is not
an immediate "must fix" bug, but a property that should inform our
selection of a new random algorithm in the coming future.


Reply to this email directly or view it on GitHub
#25 (comment).

@idontgetoutmuch
Copy link
Member Author

@gbaz by "guarantees made by the random library have never suggested otherwise" do you mean the haddock comment

but very little work has been done on statistically robust implementations of split ([System.Random,System.Random] are the only examples we know of)

or the comment in the actual implementation

-- no statistical foundation for this!

or is there something I am missing?

@gbaz
Copy link

gbaz commented Apr 10, 2015

The result of repeatedly using next should be at least as statistically robust as the Minimal Standard Random Number Generator described by [System.Random, System.Random]. Until more is known about implementations of split, all we require is that split deliver generators that are (a) not identical and (b) independently robust in the sense just given.

This makes clear to me that there was never a promise of statistical independence between split generators -- just that independently each generator is robust.

So this is well documented behaviour. (Which doesn' t mean it is good behaviour, and doesn't mean we shouldn't replace it with better behaviour now that we have new research and implementations).

@cartazio
Copy link
Contributor

agreed. And some effort and time this summer should be spent exploring the
choices

On Thu, Apr 9, 2015 at 9:28 PM, gbaz [email protected] wrote:

The result of repeatedly using next should be at least as statistically
robust as the Minimal Standard Random Number Generator described by
[System.Random, System.Random]. Until more is known about implementations
of split, all we require is that split deliver generators that are (a) not
identical and (b) independently robust in the sense just given.

This makes clear to me that there was never a promise of statistical
independence between split generators -- just that independently each
generator is robust.

So this is well documented behaviour. (Which doesn' t mean it is good
behaviour, and doesn't mean we shouldn't replace it with better behaviour
now that we have new research and implementations).


Reply to this email directly or view it on GitHub
#25 (comment).

@idontgetoutmuch
Copy link
Member Author

The second example I gave, rolling a die and getting 53668 sixes and no other numbers, does not use split just randomR.

@idontgetoutmuch
Copy link
Member Author

@gbaz
Copy link

gbaz commented Apr 16, 2015

The second example doesn't just use randomR -- it calls mkStdGen for each roll individually, which creates a new generator. As far as I know, mkStdGen in turn calls split.

Regardless, it is never considered the case that making new generators without introducing explicit randomness should somehow guarantee that the sequence of generators you make are mutually uncorrelated.

If you change the example to share the same generator, the problem does not exist. We could perhaps improve the documentation to more clearly warn against this bad usage pattern.

@dolio
Copy link

dolio commented Apr 16, 2015

The second example doesn't just use randomR -- it calls mkStdGen for each roll individually, which creates a new generator. As far as I know, mkStdGen in turn calls split.

I don't think it even does that. It just creates a new generator from a specific seed. The complaint is that seeding with N doesn't differ from seeding with (N+1) when generating a single number from 1 to 6.

@idontgetoutmuch
Copy link
Member Author

@cartazio
Copy link
Contributor

Yup. We should both work through running validation benchmarks from those
repos / audit the statistical and performance benchmarks that the student
worked on.
On Sep 17, 2015 4:01 AM, "idontgetoutmuch" [email protected] wrote:

I believe some comparison work has been done. I am recording these links
below for information.

https://github.com/nkartashov/SplitMix
https://github.com/nkartashov/prng-test
https://github.com/nkartashov/prng-bench
https://github.com/nkartashov/htestu


Reply to this email directly or view it on GitHub
#25 (comment).

@Blaisorblade
Copy link

After seeing split docs, I wanted to mention a library designed for parallel Monte Carlo: http://www.sprng.org/. This page describes the algorithms used and the docs also describe the performed testing; the library was also published on ACM ToMS with 275 citations. It also doesn't use cryptographic-strength PRNGs, unlike the ones mentioned in the 2010 haskell-cafe thread (https://mail.haskell.org/pipermail/haskell-cafe/2010-November/thread.html#85959),
and the docs mention TestU01 (the standard benchmark mentioned also in https://github.com/nkartashov/htestu).

I haven't validated the library myself, but it was recommended by my professor in Monte Carlo methods and random number generation, and he wanted to use it for his own publications. Since physicists know their stats, it looks promising.

The actual algs aren't so much math (though the validation work isn't going to be trivial). Anyone want to take a stab at this?

@cartazio
Copy link
Contributor

cartazio commented Sep 1, 2016

thanks for sharing this, I"ll take a look soon! (i've some summer projects
with september deadlines hot on my tail, but i'm keen to give random some
much needed love this fall)

On Wed, Aug 31, 2016 at 4:44 PM, Paolo G. Giarrusso <
[email protected]> wrote:

After seeing split docs, I wanted to mention a library designed for
parallel Monte Carlo: http://www.sprng.org/. This page
http://www.sprng.org/Version5.0/generators.html describes the
algorithms used and the docs also describe the performed testing; the
library was also published on ACM ToMS with 275 citations. It also
doesn't use cryptographic-strength PRNGs, unlike the ones mentioned in
the 2010 haskell-cafe thread (https://mail.haskell.org/
pipermail/haskell-cafe/2010-November/thread.html#85959),
and the docs mention TestU01 (the standard benchmark mentioned also in
https://github.com/nkartashov/htestu).

I haven't validated the library myself, but it was recommended by my
professor in Monte Carlo methods and random number generation, and he
wanted to use it for his own publications. Since physicists know their
stats, it looks promising.

The actual algs aren't so much math (though the validation work isn't
going to be trivial). Anyone want to take a stab at this?


You are receiving this because you commented.
Reply to this email directly, view it on GitHub
#25 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAAQwvFuQ2EeOJC_3ENfrjuvD9OpDySBks5qleeqgaJpZM4D2pzO
.

tommay added a commit to tommay/sudoku-in-haskell that referenced this issue Oct 4, 2016
creating the random solved puzzle and shuffling the layout.  This
porbably doesn't matter here, which is good because the generators
aren't really independent right now, as per the doc and as described
at  haskell/random#25.
tommay added a commit to tommay/sudoku-in-haskell that referenced this issue Oct 4, 2016
creating the random solved puzzle and shuffling the layout.  This
porbably doesn't matter here, which is good because the generators
aren't really independent right now, as per the doc and as described
at haskell/random#25.
tommay added a commit to tommay/sudoku-in-haskell that referenced this issue Oct 4, 2016
creating the random solved puzzle and shuffling the layout.  This
porbably doesn't matter here, which is good because the generators
aren't really independent right now, as per the doc and as described
at haskell/random#25.
@tom-bop
Copy link

tom-bop commented Feb 15, 2018

Any news on this front?

@cartazio
Copy link
Contributor

yup, https://github.com/cartazio/random/tree/v1.2.0 (plus some commits i've locally that i really should push) is progressing to a release

@tom-bop whats your needs/ context?

@cartazio
Copy link
Contributor

(i do need to figure out what the major versioning / migrration path will be, 1.2 is gonna try to be mostly drop in compatible, with minimal fix ups, some later versions will have more machinery / better apis
)

@idontgetoutmuch
Copy link
Member Author

@tom-bop my recommendation is not to use this library. If you really want independent generators then use either https://hackage.haskell.org/package/tf-random or https://hackage.haskell.org/package/splitmix.

@cartazio
Copy link
Contributor

@idontgetoutmuch
Copy link
Member Author

@cartazio excellent - that will teach me to trust people who told me it was the greatest thing since sliced bread - I will have to read the article in more depth

@cartazio
Copy link
Contributor

cartazio commented Feb 16, 2018 via email

@idontgetoutmuch
Copy link
Member Author

@cartazio
Copy link
Contributor

cartazio commented Feb 4, 2020 via email

@peteroupc
Copy link

For your information:

I have written notes on how to test PRNGs and hash functions for appropriate randomness in "Testing PRNGs for High-Quality Randomness". As relevant here, there are many kinds of hash functions that could serve as the basis for a good-quality splittable RNG construction (not just Threefry), and there are at least four kinds of sequences that are suitable for testing splittable RNGs.

curiousleo pushed a commit to curiousleo/random that referenced this issue May 5, 2020
cartazio pushed a commit that referenced this issue May 19, 2020
curiousleo added a commit to curiousleo/random that referenced this issue May 26, 2020
author Alexey Kuleshevich <[email protected]> 1581472095 +0300
committer Leonhard Markert <[email protected]> 1590493894 +0200

This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

MonadRandom
-----------

This patch adds a class 'MonadRandom':

    -- | 'MonadRandom' is an interface to monadic pseudo-random number generators.
    class Monad m => MonadRandom g s m | g m -> s where
      {-# MINIMAL freezeGen,thawGen,(uniformWord32|uniformWord64) #-}

      type Frozen g = (f :: Type) | f -> g
      freezeGen :: g s -> m (Frozen g)
      thawGen :: Frozen g -> m (g s)

      uniformWord32 :: g s -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g s -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

Conceptually, in 'MonadRandom g s m', 'g s' is the type of the
generator, 's' is the state type, and 'm' the underlying monad. Via the
functional dependency 'g m -> s', the state type is determined by the
generator and monad.

'Frozen' is the type of the generator's state "at rest". It is defined
as an injective type family via 'f -> g', so there is no ambiguity as to
which 'g' any 'Frozen g' belongs to.

This definition is generic enough to accommodate, for example, the 'Gen'
type from the 'mwc-random' package, which itself abstracts over the
underlying primitive monad and state token. The documentation shows the
full 'MonadRandom Gen' instance.

Four 'MonadRandom' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
curiousleo added a commit to curiousleo/random that referenced this issue May 26, 2020
author Alexey Kuleshevich <[email protected]> 1581472095 +0300
committer Leonhard Markert <[email protected]> 1590493894 +0200

This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

MonadRandom
-----------

This patch adds a class 'MonadRandom':

    -- | 'MonadRandom' is an interface to monadic pseudo-random number generators.
    class Monad m => MonadRandom g s m | g m -> s where
      {-# MINIMAL freezeGen,thawGen,(uniformWord32|uniformWord64) #-}

      type Frozen g = (f :: Type) | f -> g
      freezeGen :: g s -> m (Frozen g)
      thawGen :: Frozen g -> m (g s)

      uniformWord32 :: g s -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g s -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

Conceptually, in 'MonadRandom g s m', 'g s' is the type of the
generator, 's' is the state type, and 'm' the underlying monad. Via the
functional dependency 'g m -> s', the state type is determined by the
generator and monad.

'Frozen' is the type of the generator's state "at rest". It is defined
as an injective type family via 'f -> g', so there is no ambiguity as to
which 'g' any 'Frozen g' belongs to.

This definition is generic enough to accommodate, for example, the 'Gen'
type from the 'mwc-random' package, which itself abstracts over the
underlying primitive monad and state token. The documentation shows the
full 'MonadRandom Gen' instance.

Four 'MonadRandom' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
curiousleo added a commit to curiousleo/random that referenced this issue May 26, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

MonadRandom
-----------

This patch adds a class 'MonadRandom':

    -- | 'MonadRandom' is an interface to monadic pseudo-random number generators.
    class Monad m => MonadRandom g s m | g m -> s where
      {-# MINIMAL freezeGen,thawGen,(uniformWord32|uniformWord64) #-}

      type Frozen g = (f :: Type) | f -> g
      freezeGen :: g s -> m (Frozen g)
      thawGen :: Frozen g -> m (g s)

      uniformWord32 :: g s -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g s -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

Conceptually, in 'MonadRandom g s m', 'g s' is the type of the
generator, 's' is the state type, and 'm' the underlying monad. Via the
functional dependency 'g m -> s', the state type is determined by the
generator and monad.

'Frozen' is the type of the generator's state "at rest". It is defined
as an injective type family via 'f -> g', so there is no ambiguity as to
which 'g' any 'Frozen g' belongs to.

This definition is generic enough to accommodate, for example, the 'Gen'
type from the 'mwc-random' package, which itself abstracts over the
underlying primitive monad and state token. The documentation shows the
full 'MonadRandom Gen' instance.

Four 'MonadRandom' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
lehins added a commit to idontgetoutmuch/random that referenced this issue May 27, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

MonadRandom
-----------

This patch adds a class 'MonadRandom':

    -- | 'MonadRandom' is an interface to monadic pseudo-random number generators.
    class Monad m => MonadRandom g s m | g m -> s where
      {-# MINIMAL freezeGen,thawGen,(uniformWord32|uniformWord64) #-}

      type Frozen g = (f :: Type) | f -> g
      freezeGen :: g s -> m (Frozen g)
      thawGen :: Frozen g -> m (g s)

      uniformWord32 :: g s -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g s -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

Conceptually, in 'MonadRandom g s m', 'g s' is the type of the
generator, 's' is the state type, and 'm' the underlying monad. Via the
functional dependency 'g m -> s', the state type is determined by the
generator and monad.

'Frozen' is the type of the generator's state "at rest". It is defined
as an injective type family via 'f -> g', so there is no ambiguity as to
which 'g' any 'Frozen g' belongs to.

This definition is generic enough to accommodate, for example, the 'Gen'
type from the 'mwc-random' package, which itself abstracts over the
underlying primitive monad and state token. The documentation shows the
full 'MonadRandom Gen' instance.

Four 'MonadRandom' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
lehins added a commit to idontgetoutmuch/random that referenced this issue May 27, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

MonadRandom
-----------

This patch adds a class 'MonadRandom':

    -- | 'MonadRandom' is an interface to monadic pseudo-random number generators.
    class Monad m => MonadRandom g s m | g m -> s where
      {-# MINIMAL freezeGen,thawGen,(uniformWord32|uniformWord64) #-}

      type Frozen g = (f :: Type) | f -> g
      freezeGen :: g s -> m (Frozen g)
      thawGen :: Frozen g -> m (g s)

      uniformWord32 :: g s -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g s -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

Conceptually, in 'MonadRandom g s m', 'g s' is the type of the
generator, 's' is the state type, and 'm' the underlying monad. Via the
functional dependency 'g m -> s', the state type is determined by the
generator and monad.

'Frozen' is the type of the generator's state "at rest". It is defined
as an injective type family via 'f -> g', so there is no ambiguity as to
which 'g' any 'Frozen g' belongs to.

This definition is generic enough to accommodate, for example, the 'Gen'
type from the 'mwc-random' package, which itself abstracts over the
underlying primitive monad and state token. The documentation shows the
full 'MonadRandom Gen' instance.

Four 'MonadRandom' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
lehins added a commit to idontgetoutmuch/random that referenced this issue May 27, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

MonadRandom
-----------

This patch adds a class 'MonadRandom':

    -- | 'MonadRandom' is an interface to monadic pseudo-random number generators.
    class Monad m => MonadRandom g s m | g m -> s where
      {-# MINIMAL freezeGen,thawGen,(uniformWord32|uniformWord64) #-}

      type Frozen g = (f :: Type) | f -> g
      freezeGen :: g s -> m (Frozen g)
      thawGen :: Frozen g -> m (g s)

      uniformWord32 :: g s -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g s -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

Conceptually, in 'MonadRandom g s m', 'g s' is the type of the
generator, 's' is the state type, and 'm' the underlying monad. Via the
functional dependency 'g m -> s', the state type is determined by the
generator and monad.

'Frozen' is the type of the generator's state "at rest". It is defined
as an injective type family via 'f -> g', so there is no ambiguity as to
which 'g' any 'Frozen g' belongs to.

This definition is generic enough to accommodate, for example, the 'Gen'
type from the 'mwc-random' package, which itself abstracts over the
underlying primitive monad and state token. The documentation shows the
full 'MonadRandom Gen' instance.

Four 'MonadRandom' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
@lehins lehins mentioned this issue Jun 4, 2020
curiousleo added a commit to curiousleo/random that referenced this issue Jun 15, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

MonadRandom
-----------

This patch adds a class 'MonadRandom':

    -- | 'MonadRandom' is an interface to monadic pseudo-random number generators.
    class Monad m => MonadRandom g s m | g m -> s where
      {-# MINIMAL freezeGen,thawGen,(uniformWord32|uniformWord64) #-}

      type Frozen g = (f :: Type) | f -> g
      freezeGen :: g s -> m (Frozen g)
      thawGen :: Frozen g -> m (g s)

      uniformWord32 :: g s -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g s -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

Conceptually, in 'MonadRandom g s m', 'g s' is the type of the
generator, 's' is the state type, and 'm' the underlying monad. Via the
functional dependency 'g m -> s', the state type is determined by the
generator and monad.

'Frozen' is the type of the generator's state "at rest". It is defined
as an injective type family via 'f -> g', so there is no ambiguity as to
which 'g' any 'Frozen g' belongs to.

This definition is generic enough to accommodate, for example, the 'Gen'
type from the 'mwc-random' package, which itself abstracts over the
underlying primitive monad and state token. The documentation shows the
full 'MonadRandom Gen' instance.

Four 'MonadRandom' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
curiousleo added a commit to idontgetoutmuch/random that referenced this issue Jun 15, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

MonadRandom
-----------

This patch adds a class 'MonadRandom':

    -- | 'MonadRandom' is an interface to monadic pseudo-random number generators.
    class Monad m => MonadRandom g s m | g m -> s where
      {-# MINIMAL freezeGen,thawGen,(uniformWord32|uniformWord64) #-}

      type Frozen g = (f :: Type) | f -> g
      freezeGen :: g s -> m (Frozen g)
      thawGen :: Frozen g -> m (g s)

      uniformWord32 :: g s -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g s -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

Conceptually, in 'MonadRandom g s m', 'g s' is the type of the
generator, 's' is the state type, and 'm' the underlying monad. Via the
functional dependency 'g m -> s', the state type is determined by the
generator and monad.

'Frozen' is the type of the generator's state "at rest". It is defined
as an injective type family via 'f -> g', so there is no ambiguity as to
which 'g' any 'Frozen g' belongs to.

This definition is generic enough to accommodate, for example, the 'Gen'
type from the 'mwc-random' package, which itself abstracts over the
underlying primitive monad and state token. The documentation shows the
full 'MonadRandom Gen' instance.

Four 'MonadRandom' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
curiousleo added a commit to idontgetoutmuch/random that referenced this issue Jun 22, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

StatefulGen
-----------

This patch adds a class 'StatefulGen':

    -- | 'StatefulGen' is an interface to monadic pseudo-random number generators.
    class Monad m => StatefulGen g m where
      uniformWord32 :: g -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

In 'StatefulGen g m', 'g' is the type of the generator and 'm' the underlying
monad.

Four 'StatefulGen' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

FrozenGen
---------

This patch also introduces a class 'FrozenGen':

    -- | 'FrozenGen' is designed for stateful pseudo-random number generators
    -- that can be saved as and restored from an immutable data type.
    class StatefulGen (MutableGen f m) m => FrozenGen f m where
      type MutableGen f m = (g :: Type) | g -> f
      freezeGen :: MutableGen f m -> m f
      thawGen :: f -> m (MutableGen f m)

'f' is the type of the generator's state "at rest" and 'm' the underlying
monad. 'MutableGen' is defined as an injective type family via 'g -> f' so for
any generator 'g', the type 'f' of its at-rest state is well-defined.

Both 'StatefulGen' and 'FrozenGen' are generic enough to accommodate, for
example, the 'Gen' type from the 'mwc-random' package, which itself abstracts
over the underlying primitive monad and state token. The documentation shows
the full instances.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
curiousleo added a commit to idontgetoutmuch/random that referenced this issue Jun 22, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word8      |         14 |         0.03 |         422|
| pure/uniform/Word16     |         13 |         0.03 |         375|
| pure/uniform/Word32     |         21 |         0.03 |         594|
| pure/uniform/Word64     |         42 |         0.03 |        1283|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int8       |         15 |         0.03 |         511|
| pure/uniform/Int16      |         15 |         0.03 |         507|
| pure/uniform/Int32      |         22 |         0.03 |         749|
| pure/uniform/Int64      |         44 |         0.03 |        1405|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|
| pure/uniform/CChar      |         14 |         0.03 |         485|
| pure/uniform/CSChar     |         14 |         0.03 |         455|
| pure/uniform/CUChar     |         13 |         0.03 |         448|
| pure/uniform/CShort     |         14 |         0.03 |         473|
| pure/uniform/CUShort    |         13 |         0.03 |         457|
| pure/uniform/CInt       |         21 |         0.03 |         737|
| pure/uniform/CUInt      |         21 |         0.03 |         742|
| pure/uniform/CLong      |         43 |         0.03 |        1544|
| pure/uniform/CULong     |         42 |         0.03 |        1460|
| pure/uniform/CPtrdiff   |         43 |         0.03 |        1494|
| pure/uniform/CSize      |         43 |         0.03 |        1475|
| pure/uniform/CWchar     |         22 |         0.03 |         785|
| pure/uniform/CSigAtomic |         21 |         0.03 |         749|
| pure/uniform/CLLong     |         43 |         0.03 |        1554|
| pure/uniform/CULLong    |         42 |         0.03 |        1505|
| pure/uniform/CIntPtr    |         43 |         0.03 |        1476|
| pure/uniform/CUIntPtr   |         42 |         0.03 |        1463|
| pure/uniform/CIntMax    |         43 |         0.03 |        1535|
| pure/uniform/CUIntMax   |         42 |         0.03 |        1493|

API changes
===========

StatefulGen
-----------

This patch adds a class 'StatefulGen':

    -- | 'StatefulGen' is an interface to monadic pseudo-random number generators.
    class Monad m => StatefulGen g m where
      uniformWord32 :: g -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

In 'StatefulGen g m', 'g' is the type of the generator and 'm' the underlying
monad.

Four 'StatefulGen' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

FrozenGen
---------

This patch also introduces a class 'FrozenGen':

    -- | 'FrozenGen' is designed for stateful pseudo-random number generators
    -- that can be saved as and restored from an immutable data type.
    class StatefulGen (MutableGen f m) m => FrozenGen f m where
      type MutableGen f m = (g :: Type) | g -> f
      freezeGen :: MutableGen f m -> m f
      thawGen :: f -> m (MutableGen f m)

'f' is the type of the generator's state "at rest" and 'm' the underlying
monad. 'MutableGen' is defined as an injective type family via 'g -> f' so for
any generator 'g', the type 'f' of its at-rest state is well-defined.

Both 'StatefulGen' and 'FrozenGen' are generic enough to accommodate, for
example, the 'Gen' type from the 'mwc-random' package, which itself abstracts
over the underlying primitive monad and state token. The documentation shows
the full instances.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.10' (GHC-8.2)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
curiousleo added a commit to idontgetoutmuch/random that referenced this issue Jun 23, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|

API changes
===========

StatefulGen
-----------

This patch adds a class 'StatefulGen':

    -- | 'StatefulGen' is an interface to monadic pseudo-random number generators.
    class Monad m => StatefulGen g m where
      uniformWord32 :: g -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

In 'StatefulGen g m', 'g' is the type of the generator and 'm' the underlying
monad.

Four 'StatefulGen' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

FrozenGen
---------

This patch also introduces a class 'FrozenGen':

    -- | 'FrozenGen' is designed for stateful pseudo-random number generators
    -- that can be saved as and restored from an immutable data type.
    class StatefulGen (MutableGen f m) m => FrozenGen f m where
      type MutableGen f m = (g :: Type) | g -> f
      freezeGen :: MutableGen f m -> m f
      thawGen :: f -> m (MutableGen f m)

'f' is the type of the generator's state "at rest" and 'm' the underlying
monad. 'MutableGen' is defined as an injective type family via 'g -> f' so for
any generator 'g', the type 'f' of its at-rest state is well-defined.

Both 'StatefulGen' and 'FrozenGen' are generic enough to accommodate, for
example, the 'Gen' type from the 'mwc-random' package, which itself abstracts
over the underlying primitive monad and state token. The documentation shows
the full instances.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.8' (GHC-7.10)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
curiousleo added a commit to idontgetoutmuch/random that referenced this issue Jun 23, 2020
This patch is mostly backwards compatible. See "Breaking Changes" below
for the full list of backwards incompatible changes.

This patch fixes quality and performance issues, addresses additional
miscellaneous issues, and introduces a monadic API.

Issues addressed
================

Priority issues fixed in this patch:

- Title: "The seeds generated by split are not independent"
  Link:  haskell#25
  Fixed: changed algorithm to SplitMix, which provides a robust 'split'
  operation

- Title: "Very low throughput"
  Link:  haskell#51
  Fixed: see "Performance" below

Additional issues addressed in this patch:

- Title: "Add Random instances for tuples"
  Link:  haskell#26
  Addressed: added 'Uniform' instances for up to 6-tuples

- Title: "Add Random instance for Natural"
  Link:  haskell#44
  Addressed: added 'UniformRange' instance for 'Natural'

- Title: "incorrect distribution of randomR for floating-point numbers"
  Link:  haskell#53
  Addressed: see "Regarding floating-point numbers" below

- Title: "System/Random.hs:43:1: warning: [-Wtabs]"
  Link:  haskell#55
  Fixed: no more tabs

- Title: "Why does random for Float and Double produce exactly 24 or 53 bits?"
  Link:  haskell#58
  Fixed: see "Regarding floating-point numbers" below

- Title: "read :: StdGen fails for strings longer than 6"
  Link:  haskell#59
  Addressed: 'StdGen' is no longer an instance of 'Read'

Regarding floating-point numbers: with this patch, the relevant
instances for 'Float' and 'Double' sample more bits than before but do
not sample every possible representable value. The documentation now
clearly spells out what this means for users.

Quality (issue 25)
==================

The algorithm [1] in version 1.1 of this library fails empirical PRNG
tests when used to generate "split sequences" as proposed in [3].

SplitMix [2] passes the same tests. This patch changes 'StdGen' to use
the SplitMix implementation provided by the splitmix package.

Test batteries used: dieharder, TestU1, PractRand.

[1]: P. L'Ecuyer, "Efficient and portable combined random number
generators". https://doi.org/10.1145/62959.62969

[2]: G. L. Steele, D. Lea, C. H. Flood, "Fast splittable pseudorandom
number generators". https://doi.org/10.1145/2714064.2660195

[3]: H. G. Schaathun, "Evaluation of splittable pseudo-random
generators". https://doi.org/10.1017/S095679681500012X

Performance (issue 51)
======================

The "improvement" column in the following table is a multiplier: the
improvement for 'random' for type 'Float' is 1038, so this operation is
1038 times faster with this patch.

| Name                    | Mean (1.1) | Mean (patch) | Improvement|
| ----------------------- | ---------- | ------------ | ---------- |
| pure/random/Float       |         30 |         0.03 |        1038|
| pure/random/Double      |         52 |         0.03 |        1672|
| pure/random/Integer     |         43 |         0.33 |         131|
| pure/uniform/Word       |         44 |         0.03 |        1491|
| pure/uniform/Int        |         43 |         0.03 |        1512|
| pure/uniform/Char       |         17 |         0.49 |          35|
| pure/uniform/Bool       |         18 |         0.03 |         618|

API changes
===========

StatefulGen
-----------

This patch adds a class 'StatefulGen':

    -- | 'StatefulGen' is an interface to monadic pseudo-random number generators.
    class Monad m => StatefulGen g m where
      uniformWord32 :: g -> m Word32 -- default implementation in terms of uniformWord64
      uniformWord64 :: g -> m Word64 -- default implementation in terms of uniformWord32
      -- plus methods for other word sizes and for byte strings
      -- all have default implementations so the MINIMAL pragma holds

In 'StatefulGen g m', 'g' is the type of the generator and 'm' the underlying
monad.

Four 'StatefulGen' instances ("monadic adapters") are provided for pure
generators to enable their use in monadic code. The documentation
describes them in detail.

FrozenGen
---------

This patch also introduces a class 'FrozenGen':

    -- | 'FrozenGen' is designed for stateful pseudo-random number generators
    -- that can be saved as and restored from an immutable data type.
    class StatefulGen (MutableGen f m) m => FrozenGen f m where
      type MutableGen f m = (g :: Type) | g -> f
      freezeGen :: MutableGen f m -> m f
      thawGen :: f -> m (MutableGen f m)

'f' is the type of the generator's state "at rest" and 'm' the underlying
monad. 'MutableGen' is defined as an injective type family via 'g -> f' so for
any generator 'g', the type 'f' of its at-rest state is well-defined.

Both 'StatefulGen' and 'FrozenGen' are generic enough to accommodate, for
example, the 'Gen' type from the 'mwc-random' package, which itself abstracts
over the underlying primitive monad and state token. The documentation shows
the full instances.

'Uniform' and 'UniformRange'
----------------------------

The 'Random' typeclass has conceptually been split into 'Uniform' and
'UniformRange'. The 'Random' typeclass is still included for backwards
compatibility. 'Uniform' is for types where it is possible to sample
from the type's entire domain; 'UniformRange' is for types where one can
sample from a specified range.

Breaking Changes
================

This patch introduces these breaking changes:

* requires 'base >= 4.8' (GHC-7.10)
* 'StdGen' is no longer an instance of 'Read'
* 'randomIO' and 'randomRIO' where extracted from the 'Random' class into
  separate functions

In addition, there may be import clashes with new functions, e.g. 'uniform' and
'uniformR'.

Deprecations
============

This patch introduces 'genWord64', 'genWord32' and similar methods to
the 'RandomGen' class. The significantly slower method 'next' and its
companion 'genRange' are now deprecated.

Co-authored-by: Alexey Kuleshevich <[email protected]>
Co-authored-by: idontgetoutmuch <[email protected]>
Co-authored-by: Leonhard Markert <[email protected]>
@lehins lehins added this to the 1.2.0 milestone Jan 23, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

8 participants