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


-- | Table-driven generation of random variates. This approach can generate
--   random variates in <i>O(1)</i> 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 <i>O(1)</i>. Note that probability is
--   quantized in units of <tt>1/2^32</tt>, and all distributions with
--   infinite support (e.g. Poisson) should be truncated.
data CondensedTable (v :: Type -> Type) a

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

-- | A <a>CondensedTable</a> 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 <a>tableFromProbabilities</a> 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 <tt>2^32</tt> at least approximately. This function will
--   correct small deviations from <tt>2^32</tt> 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 λ &lt; 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
--   <a>System.Random.MWC.CondensedTable</a> 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
--   <a>categorical</a>.
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 <a>geometric0</a>
--   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:
--   
--   &lt;math&gt;
binomial :: StatefulGen g m => Int -> Double -> g -> m Int

-- | Random variate generate for Poisson distribution.
--   
--   If parameter λ is within 10 σ or greater than <tt>maxBound :: Int</tt>
--   error is raised since result may not be representable as <tt>Int</tt>
poisson :: StatefulGen g m => 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 <i>[0 .. n-1]</i>.
--   
--   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 <tt><i>dev</i>urandom</tt>. On Windows, it will
--   internally use <tt>RtlGenRandom</tt>.
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
--   &lt;math&gt; 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: <a>Gen</a> which
--   is generator that uses in-place mutation and <a>Seed</a> which is
--   immutable snapshot of generator's state.
--   
--   <h2>Initialization</h2>
--   
--   Generator could be initialized in several ways. One is to obtain
--   randomness from operating system using <a>createSystemRandom</a>,
--   <a>createSystemSeed</a> or <a>withSystemRandomST</a> (All examples
--   assume that <tt>System.Random.Stateful</tt> is imported)
--   
--   <pre>
--   &gt;&gt;&gt; g &lt;- createSystemRandom
--   
--   &gt;&gt;&gt; uniformM g :: IO Int
--   ...
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; withSystemRandomST $ \g -&gt; uniformM g :: IO Int
--   ...
--   </pre>
--   
--   Deterministically create generator from given seed using
--   <a>initialize</a> function:
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Int
--   
--   &gt;&gt;&gt; import qualified Data.Vector.Unboxed as U
--   
--   &gt;&gt;&gt; import System.Random.Stateful
--   
--   &gt;&gt;&gt; g &lt;- initialize $ U.fromList [1,2,3]
--   
--   &gt;&gt;&gt; uniformRM (1,200) g :: IO Int64
--   101
--   </pre>
--   
--   Last way is to create generator with fixed seed which could be useful
--   in testing
--   
--   <pre>
--   &gt;&gt;&gt; g &lt;- create
--   
--   &gt;&gt;&gt; uniformM g :: IO Int
--   -8765701622605876598
--   </pre>
--   
--   <h2>Generation of random numbers</h2>
--   
--   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
--   <tt>UniformRange</tt> and <tt>Uniform</tt> 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:
--   
--   <pre>
--   &gt;&gt;&gt; g &lt;- create
--   
--   &gt;&gt;&gt; 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]
--   </pre>
--   
--   For generating full range of possible values one could use
--   <tt>uniformM</tt>. This example generates 10 random bytes, or
--   equivalently 10 throws of 256-sided dice:
--   
--   <pre>
--   &gt;&gt;&gt; g &lt;- create
--   
--   &gt;&gt;&gt; replicateM 10 $ uniformM g :: IO [Word8]
--   [209,138,126,150,165,15,69,203,155,146]
--   </pre>
--   
--   There are special functions for generation of <tt>Doubles</tt> and
--   @Float in unit interval: <a>uniformDouble01M</a>,
--   <a>uniformDoublePositive01M</a>, <a>uniformFloat01M</a>,
--   <a>uniformFloatPositive01M</a>:
--   
--   <pre>
--   &gt;&gt;&gt; uniformDouble01M =&lt;&lt; create
--   0.5248103628705498
--   
--   &gt;&gt;&gt; uniformFloat01M =&lt;&lt; create
--   0.5248104
--   </pre>
--   
--   For normal distribution and others see modules
--   <a>System.Random.MWC.Distributions</a> and
--   <a>System.Random.MWC.CondensedTable</a>. Note that they could be used
--   with any other generator implementing <a>StatefulGen</a> 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:
--   
--   <pre>
--   &gt;&gt;&gt; g &lt;- create
--   
--   &gt;&gt;&gt; uniformVector g 10 :: IO (U.Vector Word8)
--   [209,138,126,150,165,15,69,203,155,146]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.ByteString as BS
--   
--   &gt;&gt;&gt; g &lt;- create
--   
--   &gt;&gt;&gt; BS.unpack &lt;$&gt; uniformByteStringM 10 g
--   [138,242,130,33,209,248,89,134,150,180]
--   </pre>
--   
--   Note that <a>uniformByteStringM</a> produces different result from
--   <a>uniformVector</a> since it uses PRNG's output more efficiently.
--   
--   <h2>State handling</h2>
--   
--   For repeatability, the state of the generator can be snapshotted and
--   replayed using the <a>save</a> and <a>restore</a> functions. Following
--   example shows how to save and restore generator:
--   
--   <pre>
--   &gt;&gt;&gt; g &lt;- create
--   
--   &gt;&gt;&gt; replicateM_ 10 (uniformM g :: IO Word64)
--   
--   &gt;&gt;&gt; s &lt;- save g
--   
--   &gt;&gt;&gt; uniformM g :: IO Word32
--   1771812561
--   
--   &gt;&gt;&gt; uniformM =&lt;&lt; restore s :: IO Word32
--   1771812561
--   </pre>
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:
--   
--   <pre>
--   initialize (singleton 42)
--   </pre>
--   
--   <pre>
--   initialize (fromList [4, 8, 15, 16, 23, 42])
--   </pre>
--   
--   If a seed contains fewer than 256 elements, it is first used verbatim,
--   then its elements are <a>xor</a>ed against elements of the default
--   seed until 256 elements are reached.
--   
--   If a seed contains exactly 258 elements, then the last two elements
--   are used to set the generator's initial state. This allows for
--   complete generator reproducibility, so that e.g. <tt>gen' == gen</tt>
--   in the following example:
--   
--   <pre>
--   gen' &lt;- <a>initialize</a> . <a>fromSeed</a> =&lt;&lt; <a>save</a>
--   </pre>
--   
--   In the MWC algorithm, the <i>carry</i> value must be strictly smaller
--   than the multiplicator (see
--   <a>https://en.wikipedia.org/wiki/Multiply-with-carry)</a>. Hence, if a
--   seed contains exactly 258 elements, the <i>carry</i> value, which is
--   the last of the 258 values, is moduloed by the multiplicator.
--   
--   Note that if the <i>first</i> 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 <a>uniformWord32</a>), 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 <a>IO</a> monad.
type GenIO = Gen PrimState IO

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

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

-- | Constrain the type of an action to run in the <a>ST</a> monad.
asGenST :: (GenST s -> ST s a) -> GenST s -> ST s a
class Uniform a
uniformM :: (Uniform a, StatefulGen g m) => g -> m a
class UniformRange a
uniformRM :: (UniformRange a, StatefulGen g m) => (a, a) -> g -> m a

-- | NOTE: Consider use of more principled type classes <a>Uniform</a> and
--   <a>UniformRange</a> 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.
--   
--   <i>Note</i>: 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:
--   
--   <ul>
--   <li>For fixed-width integral types, the type's entire range is
--   used.</li>
--   <li>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 <a>log</a>
--   function).</li>
--   </ul>
--   
--   To generate a <a>Float</a> variate with a range of [0,1), subtract
--   2**(-33). To do the same with <a>Double</a> variates, subtract
--   2**(-53).
uniform :: (Variate a, PrimMonad m) => Gen (PrimState m) -> m a

-- | Generate single uniformly distributed random variable in a given
--   range.
--   
--   <ul>
--   <li>For integral types inclusive range is used.</li>
--   <li>For floating point numbers range (a,b] is used if one ignores
--   rounding errors.</li>
--   </ul>
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 <a>uniform</a> 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 <a>Gen</a>.
data Seed

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

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

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

-- | Create a new <a>Gen</a> that mirrors the state of a saved <a>Seed</a>.
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:
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- withSystemRandom $ \_ -&gt; newSTRef 1
--   
--   &gt;&gt;&gt; withSystemRandom $ \_ -&gt; modifySTRef ref succ &gt;&gt; readSTRef ref
--   2
--   
--   &gt;&gt;&gt; withSystemRandom $ \_ -&gt; modifySTRef ref succ &gt;&gt; readSTRef ref
--   3
--   </pre>

-- | <i>Deprecated: Use withSystemRandomST or createSystemSeed or
--   createSystemRandom instead</i>
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
