-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Fast, high quality pseudo random number generation
--   
--   This package contains code for generating high quality random numbers
--   that follow either a uniform or normal distribution. The generated
--   numbers are suitable for use in statistical applications. . The
--   uniform PRNG uses Marsaglia's MWC256 (also known as MWC8222)
--   multiply-with-carry generator, which has a period of 2^8222 and fares
--   well in tests of randomness. It is also extremely fast, between 2 and
--   3 times faster than the Mersenne Twister. . Compared to the
--   mersenne-random package, this package has a more convenient API, is
--   faster, and supports more statistical distributions.
@package mwc-random
@version 0.15.2.0

-- | Table-driven generation of random variates. This approach can generate
--   random variates in O(1) time for the supported distributions,
--   at a modest cost in initialization time.
module System.Random.MWC.CondensedTable

-- | A lookup table for arbitrary discrete distributions. It allows the
--   generation of random variates in O(1). Note that probability is
--   quantized in units of 1/2^32, and all distributions with
--   infinite support (e.g. Poisson) should be truncated.
data CondensedTable (v :: Type -> Type) a

-- | A CondensedTable that uses boxed vectors, and is able to hold
--   any type of element.
type CondensedTableV = CondensedTable Vector

-- | A CondensedTable that uses unboxed vectors.
type CondensedTableU = CondensedTable Vector

-- | Generate a random value using a condensed table.
genFromTable :: forall g m (v :: Type -> Type) a. (StatefulGen g m, Vector v a) => CondensedTable v a -> g -> m a

-- | Generate a condensed lookup table from a list of outcomes with given
--   probabilities. The vector should be non-empty and the probabilities
--   should be non-negative and sum to 1. If this is not the case, this
--   algorithm will construct a table for some distribution that may bear
--   no resemblance to what you intended.
tableFromProbabilities :: (Vector v (a, Word32), Vector v (a, Double), Vector v a, Vector v Word32) => v (a, Double) -> CondensedTable v a

-- | Same as tableFromProbabilities but treats number as weights not
--   probilities. Non-positive weights are discarded, and those remaining
--   are normalized to 1.
tableFromWeights :: (Vector v (a, Word32), Vector v (a, Double), Vector v a, Vector v Word32) => v (a, Double) -> CondensedTable v a

-- | Generate a condensed lookup table from integer weights. Weights should
--   sum to 2^32 at least approximately. This function will
--   correct small deviations from 2^32 such as arising from
--   rounding errors. But for large deviations it's likely to product
--   incorrect result with terrible performance.
tableFromIntWeights :: (Vector v (a, Word32), Vector v a, Vector v Word32) => v (a, Word32) -> CondensedTable v a

-- | Create a lookup table for the Poisson distribution. Note that table
--   construction may have significant cost. For λ < 100 it takes as
--   much time to build table as generation of 1000-30000 variates.
tablePoisson :: Double -> CondensedTableU Int

-- | Create a lookup table for the binomial distribution.
tableBinomial :: Int -> Double -> CondensedTableU Int

-- | Pseudo-random number generation for non-uniform distributions.
module System.Random.MWC.Distributions

-- | Generate a normally distributed random variate with given mean and
--   standard deviation.
normal :: StatefulGen g m => Double -> Double -> g -> m Double

-- | Generate a normally distributed random variate with zero mean and unit
--   variance.
--   
--   The implementation uses Doornik's modified ziggurat algorithm.
--   Compared to the ziggurat algorithm usually used, this is slower, but
--   generates more independent variates that pass stringent tests of
--   randomness.
standard :: StatefulGen g m => g -> m Double

-- | Generate an exponentially distributed random variate.
exponential :: StatefulGen g m => Double -> g -> m Double

-- | Generate truncated exponentially distributed random variate.
truncatedExp :: StatefulGen g m => Double -> (Double, Double) -> g -> m Double

-- | Random variate generator for gamma distribution.
gamma :: StatefulGen g m => Double -> Double -> g -> m Double

-- | Random variate generator for the chi square distribution.
chiSquare :: StatefulGen g m => Int -> g -> m Double

-- | Random variate generator for Beta distribution
beta :: StatefulGen g m => Double -> Double -> g -> m Double

-- | Random variate generator for categorical distribution.
--   
--   Note that if you need to generate a lot of variates functions
--   System.Random.MWC.CondensedTable will offer better performance.
--   If only few is needed this function will faster since it avoids costs
--   of setting up table.
categorical :: (StatefulGen g m, Vector v Double) => v Double -> g -> m Int

-- | Random variate generator for categorical distribution where the
--   weights are in the log domain. It's implemented in terms of
--   categorical.
logCategorical :: (StatefulGen g m, Vector v Double) => v Double -> g -> m Int

-- | Random variate generator for the geometric distribution, computing the
--   number of failures before success. Distribution's support is [0..].
geometric0 :: StatefulGen g m => Double -> g -> m Int

-- | Random variate generator for geometric distribution for number of
--   trials. Distribution's support is [1..] (i.e. just geometric0
--   shifted by 1).
geometric1 :: StatefulGen g m => Double -> g -> m Int

-- | Random variate generator for Bernoulli distribution
bernoulli :: StatefulGen g m => Double -> g -> m Bool

-- | Random variate generator for Binomial distribution. Will throw
--   exception when parameters are out range.
--   
--   The probability of getting exactly k successes in n trials is given by
--   the probability mass function:
--   
--   <math>
binomial :: StatefulGen g m => Int -> Double -> g -> m Int

-- | Random variate generator for Dirichlet distribution
dirichlet :: (StatefulGen g m, Traversable t) => t Double -> g -> m (t Double)

-- | Random variate generator for uniformly distributed permutations. It
--   returns random permutation of vector [0 .. n-1].
--   
--   This is the Fisher-Yates shuffle
uniformPermutation :: (StatefulGen g m, PrimMonad m, Vector v Int) => Int -> g -> m (v Int)

-- | Random variate generator for a uniformly distributed shuffle (all
--   shuffles are equiprobable) of a vector. It uses Fisher-Yates shuffle
--   algorithm.
uniformShuffle :: (StatefulGen g m, PrimMonad m, Vector v a) => v a -> g -> m (v a)

-- | In-place uniformly distributed shuffle (all shuffles are
--   equiprobable)of a vector.
uniformShuffleM :: (StatefulGen g m, PrimMonad m, MVector v a) => v (PrimState m) a -> g -> m ()

-- | Low level source of random values for seeds. It should work on both
--   unices and windows
module System.Random.MWC.SeedSource

-- | Acquire seed from the system entropy source. On Unix machines, this
--   will attempt to use devurandom. On Windows, it will
--   internally use RtlGenRandom.
acquireSeedSystem :: Storable a => Int -> IO [a]
acquireSeedTime :: IO [Word32]

-- | Name of source of randomness. It should be used in error messages
randomSourceName :: String

-- | Pseudo-random number generation using Marsaglia's MWC256, (also known
--   as MWC8222) multiply-with-carry generator, which has a period of
--   <math> and fares well in tests of randomness. It is also
--   extremely fast, between 2 and 3 times faster than the Mersenne
--   Twister. There are two representation of generator: Gen which
--   is generator that uses in-place mutation and Seed which is
--   immutable snapshot of generator's state.
--   
--   
Initialization
--   
--   Generator could be initialized in several ways. One is to obtain
--   randomness from operating system using createSystemRandom,
--   createSystemSeed or withSystemRandomST (All examples
--   assume that System.Random.Stateful is imported)
--   
--   
--   >>> g <- createSystemRandom
--   
--   >>> uniformM g :: IO Int
--   ...
--   
--   
--   
--   >>> withSystemRandomST $ \g -> uniformM g :: IO Int
--   ...
--   
--   
--   Deterministically create generator from given seed using
--   initialize function:
--   
--   
--   >>> import Data.Int
--   
--   >>> import qualified Data.Vector.Unboxed as U
--   
--   >>> import System.Random.Stateful
--   
--   >>> g <- initialize $ U.fromList [1,2,3]
--   
--   >>> uniformRM (1,200) g :: IO Int64
--   101
--   
--   
--   Last way is to create generator with fixed seed which could be useful
--   in testing
--   
--   
--   >>> g <- create
--   
--   >>> uniformM g :: IO Int
--   -8765701622605876598
--   
--   
--   
Generation of random numbers
--   
--   Recommended way of generating random numbers in simple cases like
--   generating uniformly distributed random number in range or value
--   uniformly distributed in complete type domain is to use
--   UniformRange and Uniform type classes. Note that
--   while small self-contained examples usually require explicit
--   annotations usually result type could be inferred.
--   
--   This example simulates 20 throws of fair 6-sided dice:
--   
--   
--   >>> g <- create
--   
--   >>> replicateM 20 $ uniformRM (1, 6::Integer) g
--   [3,4,3,1,4,6,1,6,1,4,2,2,3,2,4,2,5,1,3,5]
--   
--   
--   For generating full range of possible values one could use
--   uniformM. This example generates 10 random bytes, or
--   equivalently 10 throws of 256-sided dice:
--   
--   
--   >>> g <- create
--   
--   >>> replicateM 10 $ uniformM g :: IO [Word8]
--   [209,138,126,150,165,15,69,203,155,146]
--   
--   
--   There are special functions for generation of Doubles and
--   @Float in unit interval: uniformDouble01M,
--   uniformDoublePositive01M, uniformFloat01M,
--   uniformFloatPositive01M:
--   
--   
--   >>> uniformDouble01M =<< create
--   0.5248103628705498
--   
--   >>> uniformFloat01M =<< create
--   0.5248104
--   
--   
--   For normal distribution and others see modules
--   System.Random.MWC.Distributions and
--   System.Random.MWC.CondensedTable. Note that they could be used
--   with any other generator implementing StatefulGen API
--   
--   There're special cases for generating random vectors and bytestrings.
--   For example in order to generate random 10-byte sequences as unboxed
--   vector or bytestring:
--   
--   
--   >>> g <- create
--   
--   >>> uniformVector g 10 :: IO (U.Vector Word8)
--   [209,138,126,150,165,15,69,203,155,146]
--   
--   
--   
--   >>> import qualified Data.ByteString as BS
--   
--   >>> g <- create
--   
--   >>> BS.unpack <$> uniformByteStringM 10 g
--   [138,242,130,33,209,248,89,134,150,180]
--   
--   
--   Note that uniformByteStringM produces different result from
--   uniformVector since it uses PRNG's output more efficiently.
--   
--   
State handling
--   
--   For repeatability, the state of the generator can be snapshotted and
--   replayed using the save and restore functions. Following
--   example shows how to save and restore generator:
--   
--   
--   >>> g <- create
--   
--   >>> replicateM_ 10 (uniformM g :: IO Word64)
--   
--   >>> s <- save g
--   
--   >>> uniformM g :: IO Word32
--   1771812561
--   
--   >>> uniformM =<< restore s :: IO Word32
--   1771812561
--   
module System.Random.MWC

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

-- | Create a generator for variates using a fixed seed.
create :: PrimMonad m => m (Gen (PrimState m))

-- | Create a generator for variates using the given seed, of which up to
--   256 elements will be used. For arrays of less than 256 elements, part
--   of the default seed will be used to finish initializing the
--   generator's state.
--   
--   Examples:
--   
--   
--   initialize (singleton 42)
--   
--   
--   
--   initialize (fromList [4, 8, 15, 16, 23, 42])
--   
--   
--   If a seed contains fewer than 256 elements, it is first used verbatim,
--   then its elements are xored against elements of the default
--   seed until 256 elements are reached.
--   
--   If a seed contains exactly 258 elements, then the last two elements
--   are used to set the generator's initial state. This allows for
--   complete generator reproducibility, so that e.g. gen' == gen
--   in the following example:
--   
--   
--   gen' <- initialize . fromSeed =<< save
--   
--   
--   In the MWC algorithm, the carry value must be strictly smaller
--   than the multiplicator (see
--   https://en.wikipedia.org/wiki/Multiply-with-carry). Hence, if a
--   seed contains exactly 258 elements, the carry value, which is
--   the last of the 258 values, is moduloed by the multiplicator.
--   
--   Note that if the first carry value is strictly smaller than the
--   multiplicator, all subsequent carry values are also strictly smaller
--   than the multiplicator (a proof of this is in the comments of the code
--   of uniformWord32), hence when restoring a saved state, we have
--   the guarantee that moduloing the saved carry won't modify its value.
initialize :: (PrimMonad m, Vector v Word32) => v Word32 -> m (Gen (PrimState m))

-- | Generate random seed for generator using system's fast source of
--   pseudo-random numbers.
createSystemSeed :: IO Seed

-- | Seed a PRNG with data from the system's fast source of pseudo-random
--   numbers.
createSystemRandom :: IO GenIO

-- | Seed PRNG with data from the system's fast source of pseudo-random
--   numbers and execute computation in ST monad.
withSystemRandomST :: (forall s. () => Gen s -> ST s a) -> IO a

-- | A shorter name for PRNG state in the IO monad.
type GenIO = Gen PrimState IO

-- | A shorter name for PRNG state in the ST monad.
type GenST s = Gen PrimState ST s

-- | Constrain the type of an action to run in the IO monad.
asGenIO :: (GenIO -> IO a) -> GenIO -> IO a

-- | Constrain the type of an action to run in the ST monad.
asGenST :: (GenST s -> ST s a) -> GenST s -> ST s a

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

-- | Generates a value uniformly distributed over all possible values of
--   that type.
--   
--   There is a default implementation via Generic:
--   
--   
--   >>> :set -XDeriveGeneric -XDeriveAnyClass
--   
--   >>> import GHC.Generics (Generic)
--   
--   >>> import System.Random.Stateful
--   
--   >>> data MyBool = MyTrue | MyFalse deriving (Show, Generic, Finite, Uniform)
--   
--   >>> data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Show, Generic, Finite, Uniform)
--   
--   >>> gen <- newIOGenM (mkStdGen 42)
--   
--   >>> uniformListM 10 gen :: IO [Action]
--   [Code MyTrue,Code MyTrue,Eat Nothing,Code MyFalse,Eat (Just False),Eat (Just True),Eat Nothing,Eat (Just False),Sleep,Code MyFalse]
--   
uniformM :: (Uniform a, StatefulGen g m) => g -> m a
($dmuniformM) :: (Uniform a, StatefulGen g m, Generic a, GUniform (Rep a)) => g -> m a

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

-- | Generates a value uniformly distributed over the provided range, which
--   is interpreted as inclusive in the lower and upper bound.
--   
--   
--   
- uniformRM (1 :: Int, 4 :: Int) generates values uniformly
--   from the set <math>
--   
- uniformRM (1 :: Float, 4 :: Float) generates values
--   uniformly from the set <math>
--   
--   
--   The following law should hold to make the function always defined:
--   
--   
--   uniformRM (a, b) = uniformRM (b, a)
--   
uniformRM :: (UniformRange a, StatefulGen g m) => (a, a) -> g -> m a

-- | NOTE: Consider use of more principled type classes Uniform and
--   UniformRange instead.
--   
--   The class of types for which we can generate uniformly distributed
--   random variates.
--   
--   The uniform PRNG uses Marsaglia's MWC256 (also known as MWC8222)
--   multiply-with-carry generator, which has a period of 2^8222 and fares
--   well in tests of randomness. It is also extremely fast, between 2 and
--   3 times faster than the Mersenne Twister.
--   
--   Note: Marsaglia's PRNG is not known to be cryptographically
--   secure, so you should not use it for cryptographic operations.
class Variate a

-- | Generate a single uniformly distributed random variate. The range of
--   values produced varies by type:
--   
--   
--   
- For fixed-width integral types, the type's entire range is
--   used.
--   
- For floating point numbers, the range (0,1] is used. Zero is
--   explicitly excluded, to allow variates to be used in statistical
--   calculations that require non-zero values (e.g. uses of the log
--   function).
--   
--   
--   To generate a Float variate with a range of [0,1), subtract
--   2**(-33). To do the same with Double variates, subtract
--   2**(-53).
uniform :: (Variate a, PrimMonad m) => Gen (PrimState m) -> m a

-- | Generate single uniformly distributed random variable in a given
--   range.
--   
--   
--   
- For integral types inclusive range is used.
--   
- For floating point numbers range (a,b] is used if one ignores
--   rounding errors.
--   
uniformR :: (Variate a, PrimMonad m) => (a, a) -> Gen (PrimState m) -> m a

-- | Generate a vector of pseudo-random variates. This is not necessarily
--   faster than invoking uniform repeatedly in a loop, but it may
--   be more convenient to use in some situations.
uniformVector :: (PrimMonad m, StatefulGen g m, Uniform a, Vector v a) => g -> Int -> m (v a)

-- | An immutable snapshot of the state of a Gen.
data Seed

-- | Convert seed into vector.
fromSeed :: Seed -> Vector Word32

-- | Convert vector to Seed. It acts similarly to initialize
--   and will accept any vector. If you want to pass seed immediately to
--   restore you better call initialize directly since following law holds:
--   
--   
--   restore (toSeed v) = initialize v
--   
toSeed :: Vector v Word32 => v Word32 -> Seed

-- | Save the state of a Gen, for later use by restore.
save :: PrimMonad m => Gen (PrimState m) -> m Seed

-- | Create a new Gen that mirrors the state of a saved Seed.
restore :: PrimMonad m => Seed -> m (Gen (PrimState m))

-- | Seed a PRNG with data from the system's fast source of pseudo-random
--   numbers, then run the given action.
--   
--   This function is unsafe and for example allows STRefs or any other
--   mutable data structure to escape scope:
--   
--   
--   >>> ref <- withSystemRandom $ \_ -> newSTRef 1
--   
--   >>> withSystemRandom $ \_ -> modifySTRef ref succ >> readSTRef ref
--   2
--   
--   >>> withSystemRandom $ \_ -> modifySTRef ref succ >> readSTRef ref
--   3
--   

-- | Deprecated: Use withSystemRandomST or createSystemSeed or
--   createSystemRandom instead
withSystemRandom :: PrimBase m => (Gen (PrimState m) -> m a) -> IO a
instance GHC.Classes.Eq System.Random.MWC.Seed
instance Control.Monad.Primitive.PrimMonad m => System.Random.Internal.FrozenGen System.Random.MWC.Seed m
instance GHC.Internal.Show.Show System.Random.MWC.Seed
instance (s GHC.Types.~ Control.Monad.Primitive.PrimState m, Control.Monad.Primitive.PrimMonad m) => System.Random.Internal.StatefulGen (System.Random.MWC.Gen s) m
instance System.Random.MWC.Variate GHC.Types.Bool
instance System.Random.MWC.Variate GHC.Types.Double
instance System.Random.MWC.Variate GHC.Types.Float
instance System.Random.MWC.Variate GHC.Types.Int
instance System.Random.MWC.Variate GHC.Internal.Int.Int16
instance System.Random.MWC.Variate GHC.Internal.Int.Int32
instance System.Random.MWC.Variate GHC.Internal.Int.Int64
instance System.Random.MWC.Variate GHC.Internal.Int.Int8
instance (System.Random.MWC.Variate a, System.Random.MWC.Variate b) => System.Random.MWC.Variate (a, b)
instance (System.Random.MWC.Variate a, System.Random.MWC.Variate b, System.Random.MWC.Variate c) => System.Random.MWC.Variate (a, b, c)
instance (System.Random.MWC.Variate a, System.Random.MWC.Variate b, System.Random.MWC.Variate c, System.Random.MWC.Variate d) => System.Random.MWC.Variate (a, b, c, d)
instance System.Random.MWC.Variate GHC.Types.Word
instance System.Random.MWC.Variate GHC.Internal.Word.Word16
instance System.Random.MWC.Variate GHC.Internal.Word.Word32
instance System.Random.MWC.Variate GHC.Internal.Word.Word64
instance System.Random.MWC.Variate GHC.Internal.Word.Word8
