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


-- | DIY Markov Chains.
--   
--   This package presents a simple combinator language for Markov
--   transition operators that are useful in MCMC.
--   
--   Any transition operators sharing the same stationary distribution and
--   obeying the Markov and reversibility properties can be combined in a
--   couple of ways, such that the resulting operator preserves the
--   stationary distribution and desirable properties amenable for MCMC.
--   
--   We can deterministically concatenate operators end-to-end, or sample
--   from a collection of them according to some probability distribution.
--   See <a>Geyer, 2005</a> for details.
--   
--   A useful strategy is to hedge one's 'sampling risk' by occasionally
--   interleaving a computationally-expensive transition (such as a
--   gradient-based algorithm like Hamiltonian Monte Carlo or NUTS) with
--   cheap Metropolis transitions.
--   
--   <pre>
--   transition = frequency [
--       (9, metropolis 1.0)
--     , (1, hamiltonian 0.05 20)
--     ]
--   </pre>
--   
--   Alternatively: sample consecutively using the same algorithm, but over
--   a range of different proposal distributions.
--   
--   <pre>
--   transition = concatAllT [
--       slice 0.5
--     , slice 1.0
--     , slice 2.0
--     ]
--   </pre>
--   
--   Or just mix and match and see what happens!
--   
--   <pre>
--   transition =
--     sampleT
--       (sampleT (metropolis 0.5) (slice 0.1))
--       (sampleT (hamiltonian 0.01 20) (metropolis 2.0))
--   </pre>
--   
--   Check the test suite for example usage.
@package declarative
@version 0.3.4


-- | Transition operators can easily be tweaked to operate over an
--   <i>annealed</i> parameter space, which can be useful when sampling
--   from bumpy landscapes with isolated modes.
--   
--   This library exports a single <a>anneal</a> function that allows one
--   to run a <i>declarative</i>-compatible transition operator over a
--   space that has been annealed to a specified temperature.
--   
--   <pre>
--   import Numeric.MCMC
--   
--   annealingTransition = do
--     anneal 0.70 (metropolis 1)
--     anneal 0.05 (metropolis 1)
--     anneal 0.05 (metropolis 1)
--     anneal 0.70 (metropolis 1)
--     metropolis 1
--   </pre>
--   
--   These annealed operators can then just be used like any other:
--   
--   <pre>
--   himmelblau :: Target [Double]
--   himmelblau = Target lHimmelblau Nothing where
--     lHimmelblau :: [Double] -&gt; Double
--     lHimmelblau [x0, x1] =
--       (-1) * ((x0 * x0 + x1 - 11) ^ 2 + (x0 + x1 * x1 - 7) ^ 2)
--   
--   main :: IO ()
--   main = withSystemRandom . asGenIO $
--     mcmc 10000 [0, 0] annealingTransition himmelblau
--   </pre>
module Numeric.MCMC.Anneal

-- | An annealing transformer.
--   
--   When executed, the supplied transition operator will execute over the
--   parameter space annealed to the supplied inverse temperature.
--   
--   <pre>
--   let annealedTransition = anneal 0.30 (slice 0.5)
--   </pre>
anneal :: (Monad m, Functor f) => Double -> Transition m (Chain (f Double) b) -> Transition m (Chain (f Double) b)


-- | This module presents a simple combinator language for Markov
--   transition operators that are useful in MCMC.
--   
--   Any transition operators sharing the same stationary distribution and
--   obeying the Markov and reversibility properties can be combined in a
--   couple of ways, such that the resulting operator preserves the
--   stationary distribution and desirable properties amenable for MCMC.
--   
--   We can deterministically concatenate operators end-to-end, or sample
--   from a collection of them according to some probability distribution.
--   See <a>Geyer, 2005</a> for details.
--   
--   The result is a simple grammar for building composite,
--   property-preserving transition operators from existing ones:
--   
--   <pre>
--   transition ::= primitive <a>transition</a>
--                | concatT transition transition
--                | sampleT transition transition
--   </pre>
--   
--   In addition to the above, this module provides a number of combinators
--   for building composite transition operators. It re-exports a number of
--   production-quality transition operators from the
--   <i>mighty-metropolis</i>, <i>speedy-slice</i>, and
--   <i>hasty-hamiltonian</i> libraries.
--   
--   Markov chains can then be run over arbitrary <a>Target</a>s using
--   whatever transition operator is desired.
--   
--   <pre>
--   import Numeric.MCMC
--   import Data.Sampling.Types
--   
--   target :: [Double] -&gt; Double
--   target [x0, x1] = negate (5  *(x1 - x0 ^ 2) ^ 2 + 0.05 * (1 - x0) ^ 2)
--   
--   rosenbrock :: Target [Double]
--   rosenbrock = Target target Nothing
--   
--   transition :: Transition IO (Chain [Double] b)
--   transition =
--     concatT
--       (sampleT (metropolis 0.5) (metropolis 1.0))
--       (sampleT (slice 2.0) (slice 3.0))
--   
--   main :: IO ()
--   main = withSystemRandom . asGenIO $ mcmc 10000 [0, 0] transition rosenbrock
--   </pre>
--   
--   See the attached test suite for other examples.
module Numeric.MCMC

-- | Deterministically concat transition operators together.
concatT :: Monad m => Transition m a -> Transition m a -> Transition m a

-- | Deterministically concat a list of transition operators together.
concatAllT :: Monad m => [Transition m a] -> Transition m a

-- | Probabilistically concat transition operators together.
sampleT :: PrimMonad m => Transition m a -> Transition m a -> Transition m a

-- | Probabilistically concat transition operators together via a uniform
--   distribution.
sampleAllT :: PrimMonad m => [Transition m a] -> Transition m a

-- | Probabilistically concat transition operators together using a
--   Bernoulli distribution with the supplied success probability.
--   
--   This is just a generalization of sampleT.
bernoulliT :: PrimMonad m => Double -> Transition m a -> Transition m a -> Transition m a

-- | Probabilistically concat transition operators together using the
--   supplied frequency distribution.
--   
--   This function is more-or-less an exact copy of <a>frequency</a>,
--   except here applied to transition operators.
frequency :: PrimMonad m => [(Int, Transition m a)] -> Transition m a

-- | An annealing transformer.
--   
--   When executed, the supplied transition operator will execute over the
--   parameter space annealed to the supplied inverse temperature.
--   
--   <pre>
--   let annealedTransition = anneal 0.30 (slice 0.5)
--   </pre>
anneal :: (Monad m, Functor f) => Double -> Transition m (Chain (f Double) b) -> Transition m (Chain (f Double) b)

-- | Trace <tt>n</tt> iterations of a Markov chain and stream them to
--   stdout.
--   
--   <pre>
--   &gt;&gt;&gt; withSystemRandom . asGenIO $ mcmc 3 [0, 0] (metropolis 0.5) rosenbrock
--   -0.48939312153007863,0.13290702689491818
--   1.4541485365128892e-2,-0.4859905564050404
--   0.22487398491619448,-0.29769783186855125
--   </pre>
mcmc :: Show (t a) => Int -> t a -> Transition IO (Chain (t a) b) -> Target (t a) -> Gen RealWorld -> IO ()

-- | A generic Metropolis transition operator.
metropolis :: (Traversable f, PrimMonad m) => Double -> Transition m (Chain (f Double) b)

-- | A Hamiltonian transition operator.
hamiltonian :: (Num (IxValue (t Double)), Traversable t, FunctorWithIndex (Index (t Double)) t, Ixed (t Double), PrimMonad m, (~) * (IxValue (t Double)) Double) => Double -> Int -> Transition m (Chain (t Double) 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

-- | Class of monads which can perform primitive state-transformer actions
class Monad m => PrimMonad (m :: * -> *) where type PrimState (m :: * -> *) :: * where {
    type family PrimState (m :: * -> *) :: *;
}

-- | State token type

-- | <tt>RealWorld</tt> is deeply magical. It is <i>primitive</i>, but it
--   is not <i>unlifted</i> (hence <tt>ptrArg</tt>). We never manipulate
--   values of type <tt>RealWorld</tt>; it's only used in the type system,
--   to parameterise <tt>State#</tt>.
data RealWorld :: *