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


-- | Pseudo-random number generation. This module contains code for
--   generating high quality random numbers that follow a uniform
--   distribution.
--   
--   For non-uniform distributions, see the <a>Distributions</a> module.
--   
--   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.
--   
--   The generator state is stored in the <a>Gen</a> data type. It can be
--   created in several ways:
--   
--   <ol>
--   <li>Using the <a>withSystemRandom</a> call, which creates a random
--   state.</li>
--   <li>Supply your own seed to <a>initialize</a> function.</li>
--   <li>Finally, <a>create</a> makes a generator from a fixed seed.
--   Generators created in this way aren't really random.</li>
--   </ol>
--   
--   For repeatability, the state of the generator can be snapshotted and
--   replayed using the <a>save</a> and <a>restore</a> functions.
--   
--   The simplest use is to generate a vector of uniformly distributed
--   values:
--   
--   <pre>
--   vs &lt;- withSystemRandom (uniformVector 100)
--   </pre>
--   
--   These values can be of any type which is an instance of the class
--   <a>Variate</a>.
--   
--   To generate random values on demand, first <a>create</a> a random
--   number generator.
--   
--   <pre>
--   gen &lt;- create
--   </pre>
--   
--   Keep this generator and use it wherever random values are required.
--   Get a random value using <a>uniform</a> or <a>uniformR</a>:
--   
--   <pre>
--   v &lt;- uniform gen
--   </pre>
--   
--   <pre>
--   v &lt;- uniformR (1, 52) gen
--   </pre>
module System.Random.MWC

-- | State of the pseudo-random number generator.
data Gen s

-- | 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))

-- | 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 (toList [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>
initialize :: (PrimMonad m, Vector v Word32) => v Word32 -> m (Gen (PrimState m))

-- | Seed a PRNG with data from the system's fast source of pseudo-random
--   numbers ("/dev/urandom" on Unix-like systems), then run the given
--   action.
--   
--   This is a heavyweight function, intended to be called only
--   occasionally (e.g. once per thread). You should use the <a>Gen</a> it
--   creates to generate many random numbers.
--   
--   <i>Note</i>: on Windows, this code does not yet use the native
--   Cryptographic API as a source of random numbers (it uses the system
--   clock instead). As a result, the sequences it generates may not be
--   highly independent.
withSystemRandom :: PrimMonad m => (Gen (PrimState m) -> m a) -> IO a

-- | 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
uniform :: (Variate a, PrimMonad m) => Gen (PrimState m) -> m a
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, Variate a, Vector v a) => Gen (PrimState m) -> 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 similarily 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))
instance Typeable Seed
instance Eq Seed
instance Show Seed
instance (Variate a, Variate b, Variate c, Variate d) => Variate (a, b, c, d)
instance (Variate a, Variate b, Variate c) => Variate (a, b, c)
instance (Variate a, Variate b) => Variate (a, b)
instance Variate Word
instance Variate Int
instance Variate Double
instance Variate Float
instance Variate Bool
instance Variate Word64
instance Variate Word32
instance Variate Word16
instance Variate Word8
instance Variate Int64
instance Variate Int32
instance Variate Int16
instance Variate Int8


-- | 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 :: PrimMonad m => Double -> Double -> Gen (PrimState m) -> 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 :: PrimMonad m => Gen (PrimState m) -> m Double

-- | Generate exponentially distributed random variate.
exponential :: PrimMonad m => Double -> Gen (PrimState m) -> m Double

-- | Random variate generator for gamma distribution.
gamma :: PrimMonad m => Double -> Double -> Gen (PrimState m) -> m Double

-- | Random variate generator for chi square distribution.
chiSquare :: PrimMonad m => Int -> Gen (PrimState m) -> m Double
