mcmc-types

commit a64c23d44e41f344b2cd9dae96b5f057e7f70cc7
parent f3a20123ca4a37bd282fd16721e9148f53d171a3
Author: Jared Tobin <jared@jtobin.ca>
Date:   Tue,  6 Oct 2015 21:28:30 +1300

Documentation updates.

Diffstat:
M
Data/Sampling/Types.hs
 | 
35
++++++++++++++++++++++++++++++++++-

1 file changed, 34 insertions(+), 1 deletion(-)
diff --git a/Data/Sampling/Types.hs b/Data/Sampling/Types.hs
@@ -1,6 +1,34 @@
 {-# OPTIONS_GHC -Wall #-}
 {-# LANGUAGE RecordWildCards #-}
 
+-- |
+-- Module: Data.Sampling.Types
+-- Copyright: (c) 2015 Jared Tobin
+-- License: MIT
+--
+-- Maintainer: Jared Tobin <jared@jtobin.ca>
+-- Stability: unstable
+-- Portability: ghc
+--
+-- Common types for implementing Markov Chain Monte Carlo (MCMC) algorithms.
+--
+-- 'Target' is a product type intended to hold a log-target density function and
+-- potentially its gradient.
+--
+-- The 'Chain' type represents a kind of annotated parameter space.
+-- Technically all that's required here is the type of the parameter space
+-- itself (held here in 'chainPosition') but in practice some additional
+-- information is typically useful.  Additionally there is 'chainScore' for
+-- holding the most recent score of the chain, as well as the target itself for
+-- implementing things like annealing.  The `chainTunables` field can be used
+-- to hold arbitrary data.
+--
+-- One should avoid exploiting these features to do something nasty (like, say,
+-- invalidating the Markov property).
+--
+-- The 'Transition' type permits probabilistic transitions over some state
+-- space by way of the underlying 'Prob' monad.
+
 module Data.Sampling.Types (
     Transition
   , Chain(..)
@@ -10,7 +38,9 @@ module Data.Sampling.Types (
 import Control.Monad.Trans.State.Strict (StateT)
 import System.Random.MWC.Probability (Prob)
 
--- | A transition operator.
+-- | A generic transition operator.
+--
+--   Has access to randomness via the underlying 'Prob' monad.
 type Transition m a = StateT a (Prob m) ()
 
 -- | The @Chain@ type specifies the state of a Markov chain at any given
@@ -27,6 +57,9 @@ instance Show a => Show (Chain a b) where
 
 -- | A @Target@ consists of a function from parameter space to the reals, as
 --   well as possibly a gradient.
+--
+--   Most implementations assume a /log/-target, so records are named
+--   accordingly.
 data Target a = Target {
     lTarget  :: a -> Double
   , glTarget :: Maybe (a -> a)