-- 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.1.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 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 :: (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 :: forall g m. 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 <i>[0 .. n-1]</i>.
--   
--   This is the Fisher-Yates shuffle
uniformPermutation :: forall g m v. (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 :: forall a. 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.Show.Show System.Random.MWC.Seed
instance GHC.Classes.Eq System.Random.MWC.Seed
instance Control.Monad.Primitive.PrimMonad m => System.Random.Internal.FrozenGen System.Random.MWC.Seed m
instance System.Random.MWC.Variate GHC.Int.Int8
instance System.Random.MWC.Variate GHC.Int.Int16
instance System.Random.MWC.Variate GHC.Int.Int32
instance System.Random.MWC.Variate GHC.Int.Int64
instance System.Random.MWC.Variate GHC.Word.Word8
instance System.Random.MWC.Variate GHC.Word.Word16
instance System.Random.MWC.Variate GHC.Word.Word32
instance System.Random.MWC.Variate GHC.Word.Word64
instance System.Random.MWC.Variate GHC.Types.Bool
instance System.Random.MWC.Variate GHC.Types.Float
instance System.Random.MWC.Variate GHC.Types.Double
instance System.Random.MWC.Variate GHC.Types.Int
instance System.Random.MWC.Variate GHC.Types.Word
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 (s GHC.Types.~ Control.Monad.Primitive.PrimState m, Control.Monad.Primitive.PrimMonad m) => System.Random.Internal.StatefulGen (System.Random.MWC.Gen s) m
