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


-- | Sampling function-based probability distributions.
--   
--   A simple probability distribution type, where distributions are
--   characterized by sampling functions.
--   
--   This implementation is a thin layer over <tt>mwc-random</tt>, which
--   handles RNG state-passing automatically by using a <tt>PrimMonad</tt>
--   like <tt>IO</tt> or <tt>ST s</tt> under the hood.
--   
--   <i>Examples</i>
--   
--   Transform a distribution's support while leaving its density structure
--   invariant:
--   
--   <pre>
--   -- uniform over [0, 1] to uniform over [1, 2]
--   fmap succ uniform
--   </pre>
--   
--   Sequence distributions together using bind:
--   
--   <pre>
--   -- a beta-binomial compound distribution
--   beta 1 10 &gt;&gt;= binomial 10
--   </pre>
--   
--   Use do-notation to build complex joint distributions from composable,
--   local conditionals:
--   
--   <pre>
--   hierarchicalModel = do
--     [c, d, e, f] &lt;- replicateM 4 $ uniformR (1, 10)
--     a &lt;- gamma c d
--     b &lt;- gamma e f
--     p &lt;- beta a b
--     n &lt;- uniformR (5, 10)
--     binomial n p
--   </pre>
@package mwc-probability
@version 2.0.4


-- | A probability monad based on sampling functions, implemented as a thin
--   wrapper over the <a>mwc-random</a> library.
--   
--   Probability distributions are abstract constructs that can be
--   represented in a variety of ways. The sampling function representation
--   is particularly useful -- it's computationally efficient, and
--   collections of samples are amenable to much practical work.
--   
--   Probability monads propagate uncertainty under the hood. An expression
--   like <tt><a>beta</a> 1 8 &gt;&gt;= <a>binomial</a> 10</tt> corresponds
--   to a <a>beta-binomial</a> distribution in which the uncertainty
--   captured by <tt><a>beta</a> 1 8</tt> has been marginalized out.
--   
--   The distribution resulting from a series of effects is called the
--   <i>predictive distribution</i> of the model described by the
--   corresponding expression. The monadic structure lets one piece
--   together a hierarchical structure from simpler, local conditionals:
--   
--   <pre>
--   hierarchicalModel = do
--     [c, d, e, f] &lt;- replicateM 4 $ uniformR (1, 10)
--     a &lt;- gamma c d
--     b &lt;- gamma e f
--     p &lt;- beta a b
--     n &lt;- uniformR (5, 10)
--     binomial n p
--   </pre>
--   
--   The functor instance allows one to transforms the support of a
--   distribution while leaving its density structure invariant. For
--   example, <tt><a>uniform</a></tt> is a distribution over the 0-1
--   interval, but <tt>fmap (+ 1) uniform</tt> is the translated
--   distribution over the 1-2 interval:
--   
--   <pre>
--   &gt;&gt;&gt; create &gt;&gt;= sample (fmap (+ 1) uniform)
--   1.5480073474340754
--   </pre>
--   
--   The applicative instance guarantees that the generated samples are
--   generated independently:
--   
--   <pre>
--   &gt;&gt;&gt; create &gt;&gt;= sample ((,) &lt;$&gt; uniform &lt;*&gt; uniform)
--   </pre>
module System.Random.MWC.Probability

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

-- | Seed a PRNG with data from the system's fast source of pseudo-random
--   numbers. All the caveats of <a>withSystemRandom</a> apply here as
--   well.
createSystemRandom :: IO GenIO

-- | Seed a PRNG with data from the system's fast source of pseudo-random
--   numbers ("<tt>/dev/urandom</tt>" on Unix-like systems or
--   <tt>RtlGenRandom</tt> on Windows), then run the given action.
--   
--   This is a somewhat expensive function, and is 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.
withSystemRandom :: PrimBase m => (Gen (PrimState m) -> m a) -> IO a

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

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

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

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

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

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

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

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

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

-- | A probability distribution characterized by a sampling function.
--   
--   <pre>
--   &gt;&gt;&gt; gen &lt;- createSystemRandom
--   
--   &gt;&gt;&gt; sample uniform gen
--   0.4208881170464097
--   </pre>
newtype Prob m a
Prob :: (Gen (PrimState m) -> m a) -> Prob m a
[sample] :: Prob m a -> Gen (PrimState m) -> m a

-- | Sample from a model <tt>n</tt> times.
--   
--   <pre>
--   &gt;&gt;&gt; samples 2 uniform gen
--   [0.6738707766845254,0.9730405951541817]
--   </pre>
samples :: PrimMonad m => Int -> Prob m a -> Gen (PrimState m) -> m [a]

-- | The uniform distribution at a specified type.
--   
--   Note that <a>Double</a> and <a>Float</a> variates are defined over the
--   unit interval.
--   
--   <pre>
--   &gt;&gt;&gt; sample uniform gen :: IO Double
--   0.29308497534914946
--   
--   &gt;&gt;&gt; sample uniform gen :: IO Bool
--   False
--   </pre>
uniform :: (PrimMonad m, Variate a) => Prob m a

-- | The uniform distribution over the provided interval.
--   
--   <pre>
--   &gt;&gt;&gt; sample (uniformR (0, 1)) gen
--   0.44984153252922365
--   </pre>
uniformR :: (PrimMonad m, Variate a) => (a, a) -> Prob m a

-- | The normal or Gaussian distribution with specified mean and standard
--   deviation.
--   
--   Note that <tt>sd</tt> should be positive.
normal :: PrimMonad m => Double -> Double -> Prob m Double

-- | The standard normal or Gaussian distribution with mean 0 and standard
--   deviation 1.
standardNormal :: PrimMonad m => Prob m Double

-- | An isotropic or spherical Gaussian distribution with specified mean
--   vector and scalar standard deviation parameter.
--   
--   Note that <tt>sd</tt> should be positive.
isoNormal :: (Traversable f, PrimMonad m) => f Double -> Double -> Prob m (f Double)

-- | The log-normal distribution with specified mean and standard
--   deviation.
--   
--   Note that <tt>sd</tt> should be positive.
logNormal :: PrimMonad m => Double -> Double -> Prob m Double

-- | The exponential distribution with provided rate parameter.
--   
--   Note that <tt>r</tt> should be positive.
exponential :: PrimMonad m => Double -> Prob m Double

-- | The inverse Gaussian (also known as Wald) distribution with mean
--   parameter <tt>mu</tt> and shape parameter <tt>lambda</tt>.
--   
--   Note that both <tt>mu</tt> and <tt>lambda</tt> should be positive.
inverseGaussian :: PrimMonad m => Double -> Double -> Prob m Double

-- | The Laplace or double-exponential distribution with provided location
--   and scale parameters.
--   
--   Note that <tt>sigma</tt> should be positive.
laplace :: (Floating a, Variate a, PrimMonad m) => a -> a -> Prob m a

-- | The gamma distribution with shape parameter <tt>a</tt> and scale
--   parameter <tt>b</tt>.
--   
--   This is the parameterization used more traditionally in frequentist
--   statistics. It has the following corresponding probability density
--   function:
--   
--   <pre>
--   f(x; a, b) = 1 / (Gamma(a) * b ^ a) x ^ (a - 1) e ^ (- x / b)
--   </pre>
--   
--   Note that both parameters should be positive.
gamma :: PrimMonad m => Double -> Double -> Prob m Double

-- | The inverse-gamma distribution with shape parameter <tt>a</tt> and
--   scale parameter <tt>b</tt>.
--   
--   Note that both parameters should be positive.
inverseGamma :: PrimMonad m => Double -> Double -> Prob m Double

-- | The Normal-Gamma distribution.
--   
--   Note that the <tt>lambda</tt>, <tt>a</tt>, and <tt>b</tt> parameters
--   should be positive.
normalGamma :: PrimMonad m => Double -> Double -> Double -> Double -> Prob m Double

-- | The Weibull distribution with provided shape and scale parameters.
--   
--   Note that both parameters should be positive.
weibull :: (Floating a, Variate a, PrimMonad m) => a -> a -> Prob m a

-- | The chi-square distribution with the specified degrees of freedom.
--   
--   Note that <tt>k</tt> should be positive.
chiSquare :: PrimMonad m => Int -> Prob m Double

-- | The beta distribution with the specified shape parameters.
--   
--   Note that both parameters should be positive.
beta :: PrimMonad m => Double -> Double -> Prob m Double

-- | Generalized Student's t distribution with location parameter
--   <tt>m</tt>, scale parameter <tt>s</tt>, and degrees of freedom
--   <tt>k</tt>.
--   
--   Note that the <tt>s</tt> and <tt>k</tt> parameters should be positive.
gstudent :: PrimMonad m => Double -> Double -> Double -> Prob m Double

-- | Student's t distribution with <tt>k</tt> degrees of freedom.
--   
--   Note that <tt>k</tt> should be positive.
student :: PrimMonad m => Double -> Prob m Double

-- | The Pareto distribution with specified index <tt>a</tt> and minimum
--   <tt>xmin</tt> parameters.
--   
--   Note that both parameters should be positive.
pareto :: PrimMonad m => Double -> Double -> Prob m Double

-- | The Dirichlet distribution with the provided concentration parameters.
--   The dimension of the distribution is determined by the number of
--   concentration parameters supplied.
--   
--   <pre>
--   &gt;&gt;&gt; sample (dirichlet [0.1, 1, 10]) gen
--   [1.2375387187120799e-5,3.4952460651813816e-3,0.9964923785476316]
--   </pre>
--   
--   Note that all concentration parameters should be positive.
dirichlet :: (Traversable f, PrimMonad m) => f Double -> Prob m (f Double)

-- | The symmetric Dirichlet distribution with dimension <tt>n</tt>. The
--   provided concentration parameter is simply replicated <tt>n</tt>
--   times.
--   
--   Note that <tt>a</tt> should be positive.
symmetricDirichlet :: PrimMonad m => Int -> Double -> Prob m [Double]

-- | The discrete uniform distribution.
--   
--   <pre>
--   &gt;&gt;&gt; sample (discreteUniform [0..10]) gen
--   6
--   
--   &gt;&gt;&gt; sample (discreteUniform "abcdefghijklmnopqrstuvwxyz") gen
--   'a'
--   </pre>
discreteUniform :: (PrimMonad m, Foldable f) => f a -> Prob m a

-- | The Zipf-Mandelbrot distribution.
--   
--   Note that <tt>a</tt> should be positive, and that values close to 1
--   should be avoided as they are very computationally intensive.
--   
--   <pre>
--   &gt;&gt;&gt; samples 10 (zipf 1.1) gen
--   [11315371987423520,2746946,653,609,2,13,85,4,256184577853,50]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; samples 10 (zipf 1.5) gen
--   [19,3,3,1,1,2,1,191,2,1]
--   </pre>
zipf :: (PrimMonad m, Integral b) => Double -> Prob m b

-- | A categorical distribution defined by the supplied probabilities.
--   
--   Note that the supplied container of probabilities must sum to 1.
categorical :: (Foldable f, PrimMonad m) => f Double -> Prob m Int

-- | The Bernoulli distribution with success probability <tt>p</tt>.
bernoulli :: PrimMonad m => Double -> Prob m Bool

-- | The binomial distribution with number of trials <tt>n</tt> and success
--   probability <tt>p</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; sample (binomial 10 0.3) gen
--   4
--   </pre>
binomial :: PrimMonad m => Int -> Double -> Prob m Int

-- | The negative binomial distribution with number of trials <tt>n</tt>
--   and success probability <tt>p</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; sample (negativeBinomial 10 0.3) gen
--   21
--   </pre>
negativeBinomial :: (PrimMonad m, Integral a) => a -> Double -> Prob m Int

-- | The multinomial distribution of <tt>n</tt> trials and category
--   probabilities <tt>ps</tt>.
--   
--   Note that <tt>ps</tt> is a vector of probabilities and should sum to
--   one.
multinomial :: (Foldable f, PrimMonad m) => Int -> f Double -> Prob m [Int]

-- | The Poisson distribution with rate parameter <tt>l</tt>.
--   
--   Note that <tt>l</tt> should be positive.
poisson :: PrimMonad m => Double -> Prob m Int
instance GHC.Base.Functor m => GHC.Base.Functor (System.Random.MWC.Probability.Prob m)
instance GHC.Base.Monad m => GHC.Base.Applicative (System.Random.MWC.Probability.Prob m)
instance GHC.Base.Monad m => GHC.Base.Monad (System.Random.MWC.Probability.Prob m)
instance (GHC.Base.Monad m, GHC.Num.Num a) => GHC.Num.Num (System.Random.MWC.Probability.Prob m a)
instance Control.Monad.Trans.Class.MonadTrans System.Random.MWC.Probability.Prob
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (System.Random.MWC.Probability.Prob m)
instance Control.Monad.Primitive.PrimMonad m => Control.Monad.Primitive.PrimMonad (System.Random.MWC.Probability.Prob m)
