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


-- | Speedy slice sampling.
--   
--   Speedy slice sampling.
--   
--   This implementation of the slice sampling algorithm uses <a>lens</a>
--   as a means to operate over generic indexed traversable functors, so
--   you can expect it to work if your target function takes a list,
--   vector, map, sequence, etc. as its argument.
--   
--   Additionally you can sample over anything that's an instance of both
--   <a>Num</a> and <a>Variate</a>, which is useful in the case of discrete
--   parameters.
--   
--   Exports a <a>mcmc</a> function that prints a trace to stdout, a
--   <a>chain</a> function for collecting results in memory, and a
--   <a>slice</a> transition operator that can be used more generally.
--   
--   <pre>
--   import Numeric.MCMC.Slice
--   import Data.Sequence (Seq, index, fromList)
--   
--   bnn :: Seq Double -&gt; Double
--   bnn xs = -0.5 * (x0 ^ 2 * x1 ^ 2 + x0 ^ 2 + x1 ^ 2 - 8 * x0 - 8 * x1) where
--     x0 = index xs 0
--     x1 = index xs 1
--   
--   main :: IO ()
--   main = withSystemRandom . asGenIO $ mcmc 10000 1 (fromList [0, 0]) bnn
--   </pre>
@package speedy-slice
@version 0.3.0


-- | This implementation performs slice sampling by first finding a bracket
--   about a mode (using a simple doubling heuristic), and then doing
--   rejection sampling along it. The result is a reliable and
--   computationally inexpensive sampling routine.
--   
--   The <a>mcmc</a> function streams a trace to stdout to be processed
--   elsewhere, while the <a>slice</a> transition can be used for more
--   flexible purposes, such as working with samples in memory.
--   
--   See <a>Neal, 2003</a> for the definitive reference of the algorithm.
module Numeric.MCMC.Slice

-- | Trace <tt>n</tt> iterations of a Markov chain and stream them to
--   stdout.
--   
--   <pre>
--   &gt;&gt;&gt; let rosenbrock [x0, x1] = negate (5  *(x1 - x0 ^ 2) ^ 2 + 0.05 * (1 - x0) ^ 2)
--   
--   &gt;&gt;&gt; withSystemRandom . asGenIO $ mcmc 3 1 [0, 0] rosenbrock
--   -3.854097694213343e-2,0.16688601288358407
--   -9.310661272172682e-2,0.2562387977415508
--   -0.48500122500661846,0.46245400501919076
--   </pre>
mcmc :: (MonadIO m, PrimMonad m, Show (t a), FoldableWithIndex (Index (t a)) t, Ixed (t a), Num (IxValue (t a)), Variate (IxValue (t a))) => Int -> IxValue (t a) -> t a -> (t a -> Double) -> Gen (PrimState m) -> m ()

-- | Trace <tt>n</tt> iterations of a Markov chain and collect them in a
--   list.
--   
--   <pre>
--   &gt;&gt;&gt; results &lt;- withSystemRandom . asGenIO $ mcmc 3 1 [0, 0] rosenbrock
--   </pre>
chain :: (PrimMonad m, FoldableWithIndex (Index (f a)) f, Ixed (f a), Variate (IxValue (f a)), Num (IxValue (f a))) => Int -> IxValue (f a) -> f a -> (f a -> Double) -> Gen (PrimState m) -> m [Chain (f a) b]

-- | A slice sampling transition operator.
slice :: (PrimMonad m, FoldableWithIndex (Index (t a)) t, Ixed (t a), Num (IxValue (t a)), Variate (IxValue (t a))) => IxValue (t a) -> Transition m (Chain (t a) b)

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

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

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