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


-- | A Markov stochastic transition operator with logging
--   
--   This package provides a <a>Transition</a> type that is useful for
--   modelling (and debugging) stochastic transition kernels (used in e.g.
--   the integration of SDEs, Markov chain Monte Carlo algorithms etc.).
--   
--   It wraps the compositional random sampling functionality of
--   `mwc-probability` and offers structured logging via `logging-effect`.
@package mwc-probability-transition
@version 0.4

module System.Random.MWC.Probability.Transition

-- | A Markov transition kernel.
data Transition message s m a

-- | Construct a <a>Transition</a> from sampling, state transformation and
--   logging functions.
--   
--   NB: The three function arguments are used in the order in which they
--   appear here:
--   
--   <ol>
--   <li>a random sample <tt>w :: t</tt> is produced, using the current
--   state <tt>x :: s</tt> as input</li>
--   <li>output <tt>z :: a</tt> and next state <tt>x' :: s</tt> are
--   computed using <tt>w</tt> and <tt>x</tt></li>
--   <li>a logging message is constructed, using <tt>z</tt> and <tt>x'</tt>
--   as arguments.</li>
--   </ol>
mkTransition :: Monad m => (s -> Prob m t) -> (s -> t -> (a, s)) -> (s -> t -> a -> message) -> Transition message s m a

-- | Run a <a>Transition</a> for a number of steps, while logging each
--   iteration.
--   
--   Returns both the list of outputs and the final state.
runTransition :: Monad m => Handler m message -> Transition message s m a -> Int -> s -> Gen (PrimState m) -> m ([a], s)

-- | Run a <a>Transition</a> for a number of steps, while logging each
--   iteration.
--   
--   Returns the list of outputs.
evalTransition :: Monad m => Handler m message -> Transition message s m a -> Int -> s -> Gen (PrimState m) -> m [a]

-- | Run a <a>Transition</a> for a number of steps, while logging each
--   iteration.
--   
--   Returns the final state.
execTransition :: Monad m => Handler m message -> Transition message s m a -> Int -> s -> Gen (PrimState m) -> m s

-- | Perform one <a>Transition</a> and check output and updated state
--   against the current state, producing an Either with the result of the
--   comparison.
--   
--   Can be useful for detecting early divergence or lack of convergence
--   etc.
stepConditional :: Monad m => (a -> s -> s -> Bool) -> (a -> s -> s -> l) -> (a -> s -> s -> r) -> Handler m message -> Transition message s m a -> s -> Gen (PrimState m) -> m (Either l r)

-- | Render a logging message along with an annotation of its severity.
withSeverity :: (t -> String) -> WithSeverity t -> String

-- | Add "Severity" information to a log message. This is often used to
--   convey how significant a log message is.
data WithSeverity a
WithSeverity :: Severity -> a -> WithSeverity a

-- | Retrieve the <a>Severity</a> a message.
[msgSeverity] :: WithSeverity a -> Severity

-- | View the underlying message.
[discardSeverity] :: WithSeverity a -> a

-- | Classes of severity for log messages. These have been chosen to match
--   <tt>syslog</tt> severity levels
data Severity

-- | System is unusable. By <tt>syslog</tt> convention, this level should
--   not be used by applications.
Emergency :: Severity

-- | Should be corrected immediately.
Alert :: Severity

-- | Critical conditions.
Critical :: Severity

-- | Error conditions.
Error :: Severity

-- | May indicate that an error will occur if action is not taken.
Warning :: Severity

-- | Events that are unusual, but not error conditions.
Notice :: Severity

-- | Normal operational messages that require no action.
Informational :: Severity

-- | Information useful to developers for debugging the application.
Debug :: Severity

-- | Handlers are mechanisms to interpret the meaning of logging as an
--   action in the underlying monad. They are simply functions from log
--   messages to <tt>m</tt>-actions.
type Handler (m :: Type -> Type) message = message -> m ()

-- | <a>withFDHandler</a> creates a new <a>Handler</a> that will append a
--   given file descriptor (or <a>Handle</a>, as it is known in the "base"
--   library). Note that this <a>Handler</a> requires log messages to be of
--   type <a>Doc</a>. This abstractly specifies a pretty-printing for log
--   lines. The two arguments two <a>withFDHandler</a> determine how this
--   pretty-printing should be realised when outputting log lines.
--   
--   These <a>Handler</a>s asynchronously log messages to the given file
--   descriptor, rather than blocking.
withFDHandler :: (MonadIO io, MonadMask io) => BatchingOptions -> Handle -> Double -> Int -> (Handler io (Doc ann) -> io a) -> io a

-- | Options that be used to configure <tt>withBatchingHandler</tt>.
data BatchingOptions
BatchingOptions :: Int -> Int -> Bool -> BatchingOptions

-- | The maximum amount of time to wait between flushes
[flushMaxDelay] :: BatchingOptions -> Int

-- | The maximum amount of messages to hold in memory between flushes}
[flushMaxQueueSize] :: BatchingOptions -> Int

-- | If the <a>Handler</a> becomes full, <a>logMessage</a> will block until
--   the queue is flushed if <a>blockWhenFull</a> is <a>True</a>, otherwise
--   it will drop that message and continue.
[blockWhenFull] :: BatchingOptions -> Bool

-- | Defaults for <a>BatchingOptions</a>
--   
--   <pre>
--   <a>defaultBatchingOptions</a> = <a>BatchingOptions</a> {<a>flushMaxDelay</a> = 1000000
--                                            ,<a>flushMaxQueueSize</a> = 100
--                                            ,<a>blockWhenFull</a> = <a>True</a>}
--   </pre>
defaultBatchingOptions :: BatchingOptions

-- | Create a new batched handler. Batched handlers take batches of
--   messages to log at once, which can be more performant than logging
--   each individual message.
--   
--   A batched handler flushes under three criteria:
--   
--   <ol>
--   <li>The flush interval has elapsed and the queue is not empty.</li>
--   <li>The queue has become full and needs to be flushed.</li>
--   <li>The scope of <a>withBatchedHandler</a> is exited.</li>
--   </ol>
--   
--   Batched handlers queue size and flush period can be configured via
--   <a>BatchingOptions</a>.
withBatchedHandler :: (MonadIO io, MonadMask io) => BatchingOptions -> (NonEmpty message -> IO ()) -> (Handler io message -> io a) -> io a

-- | A handle managing output to the Haskell program's standard output
--   channel.
stdout :: Handle

-- | A handle managing output to the Haskell program's standard error
--   channel.
stderr :: Handle
instance GHC.Base.Functor m => GHC.Base.Functor (System.Random.MWC.Probability.Transition.Transition message s m)
instance GHC.Show.Show (System.Random.MWC.Probability.Transition.Transition msg s m a)
