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


-- | Monadic interface for mwc-random
--   
--   Simple monadic interface for mwc-random.
@package mwc-random-monad
@version 0.7.3.1


-- | This module provide monadic interface for <tt>mwc-random</tt> package.
--   It's just a thin wrapper and all work is done <tt>mwc-random</tt>.
module System.Random.MWC.Monad

-- | Random monad for mwc-random package
data Rand m a

-- | Convert function to Rand monad
toRand :: MonadPrim m => (Gen (PrimState (BasePrimMonad m)) -> BasePrimMonad m a) -> Rand m a

-- | Type synonim for IO-based Rand monad
type RandIO a = Rand IO a

-- | Fix type of monad to IO
asRandIO :: RandIO a -> RandIO a

-- | Type synonim for ST-based Rand monad
type RandST s a = Rand (ST s) a

-- | Fix type of monad to ST
asRandST :: RandST s a -> RandST s a

-- | Run random monad
runRand :: Rand m a -> Gen (PrimState (BasePrimMonad m)) -> m a

-- | Run monad using fixed seed
runWithCreate :: MonadPrim m => Rand m a -> m a

-- | Run monad using seed
runWithSeed :: MonadPrim m => Seed -> Rand m a -> m a

-- | By creating seed from vector of values
runWithVector :: (Vector v Word32, MonadPrim m) => Rand m a -> v Word32 -> m a

-- | Run monad using seed obtained from system's fast source of
--   pseudo-random numbers ("/dev/urandom" on Unix-like systems).
--   <tt>m</tt> must be either IO or ST.
runWithSystemRandom :: (PrimBase m, BasePrimMonad m ~ m) => Rand m a -> IO a

-- | Run monad using seed obtained from system's fast source of
--   pseudo-random numbers ("/dev/urandom" on Unix-like systems). Unlike
--   <a>runWithSystemRandom</a> it could be used with monad stacks.
runWithSystemRandomT :: (MonadPrim m, BasePrimMonad m ~ IO) => Rand m a -> m a

-- | Uniformly distributed values
uniform :: (MonadPrim m, Variate a) => Rand m a

-- | Uniformly distributed values in range
uniformR :: (MonadPrim m, Variate a) => (a, a) -> Rand m a

-- | An immutable snapshot of the state of a <a>Gen</a>.
data Seed :: *

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

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

-- | Save current seed for future reuse
save :: MonadPrim m => Rand m Seed
instance GHC.Base.Monad m => GHC.Base.Functor (System.Random.MWC.Monad.Rand m)
instance GHC.Base.Monad m => GHC.Base.Monad (System.Random.MWC.Monad.Rand m)
instance GHC.Base.Monad m => GHC.Base.Applicative (System.Random.MWC.Monad.Rand m)
instance Control.Monad.Trans.Class.MonadTrans System.Random.MWC.Monad.Rand
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (System.Random.MWC.Monad.Rand m)
instance Control.Monad.Primitive.Class.MonadPrim m => Control.Monad.Primitive.Class.MonadPrim (System.Random.MWC.Monad.Rand m)


-- | Monadic wrapper for various distributions generators.
module System.Random.MWC.Distributions.Monad

-- | Normally distributed variable
normal :: MonadPrim m => Double -> Double -> Rand m Double

-- | Normally distributed variables with mean 0 and 1 standard deviation
standard :: MonadPrim m => Rand m Double

-- | Generate exponentially distributed random variate.
exponential :: MonadPrim m => Double -> Rand m Double

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

-- | Random variate generator for gamma distribution.
gamma :: MonadPrim m => Double -> Double -> Rand m Double

-- | Random variate generator for chi square distribution.
chiSquare :: MonadPrim m => Int -> Rand m Double

-- | Random variate generator for Beta distribution
beta :: MonadPrim m => Double -> Double -> Rand 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 :: (MonadPrim m, Vector v Double) => v Double -> Rand m Int

-- | Random variate generator for the geometric distribution, computing the
--   number of failures before success. Distribution's support is [0..].
geometric0 :: MonadPrim m => Double -> Rand 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 :: MonadPrim m => Double -> Rand m Int

-- | Random variate generator for Bernoulli distribution
bernoulli :: (MonadPrim m) => Double -> Rand m Bool

-- | Random variate generator for Dirichlet distribution
dirichlet :: (MonadPrim m, Traversable t) => t Double -> Rand 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 :: (MonadPrim m, Vector v Int) => Int -> Rand m (v Int)

-- | Random variate generator for a uniformly distributed shuffle of a
--   vector.
uniformShuffle :: (MonadPrim m, Vector v a) => v a -> Rand m (v a)

-- | In-place uniformly distributed shuffle (all shuffles are equiprobable)
--   of a vector.
uniformShuffleM :: (MonadPrim m, MVector v a, PrimState m ~ PrimState (BasePrimMonad m)) => v (PrimState m) a -> Rand m ()


-- | Monadic wrapper for <a>CondesedTable</a>.
module System.Random.MWC.CondensedTable.Monad

-- | 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
genFromTable :: (MonadPrim m, Vector v a) => CondensedTable v a -> Rand m a

-- | Generate a condensed lookup table from a list of outcomes with given
--   probabilities. The vector should be non-empty and the probabilites
--   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 distibution. 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
