declarative

commit 413932f148a8fefc9fc438249b21c0091d841ccf
parent e36308dd2e22d434a353444543562f57339a7cbe
Author: Jared Tobin <jared@jtobin.ca>
Date:   Mon,  7 Nov 2016 22:18:46 +1300

Docs. [ci skip]

Diffstat:
M
lib/Numeric/MCMC/Anneal.hs
 | 
44
++++++++++++++++++++++++++++++++++++++++++++

1 file changed, 44 insertions(+), 0 deletions(-)
diff --git a/lib/Numeric/MCMC/Anneal.hs b/lib/Numeric/MCMC/Anneal.hs
@@ -1,6 +1,44 @@
 {-# OPTIONS_GHC -fno-warn-type-defaults #-}
 {-# LANGUAGE RecordWildCards #-}
 
+-- |
+-- Module: Numeric.MCMC.Anneal
+-- Copyright: (c) 2015 Jared Tobin
+-- License: MIT
+--
+-- Maintainer: Jared Tobin <jared@jtobin.ca>
+-- Stability: unstable
+-- Portability: ghc
+--
+-- Transition operators can easily be tweaked to operate over an /annealed/
+-- parameter space, which can be useful when sampling from bumpy landscapes
+-- with isolated modes.
+--
+-- This library exports a single 'anneal' function that allows one to run a
+-- /declarative/-compatible transition operator over a space that has been
+-- annealed to a specified temperature.
+--
+-- > 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
+--
+-- These annealed operators can then just be used like any other:
+--
+-- > himmelblau :: Target [Double]
+-- > himmelblau = Target lHimmelblau Nothing where
+-- >   lHimmelblau :: [Double] -> 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
+
 module Numeric.MCMC.Anneal (
     anneal
   ) where
@@ -8,6 +46,12 @@ module Numeric.MCMC.Anneal (
 import Control.Monad.Trans.State.Strict (get, modify)
 import Data.Sampling.Types (Transition, Chain(..), Target(..))
 
+-- | An annealing transformer.
+--
+--   When executed, the supplied transition operator will execute over the
+--   parameter space annealed to the supplied inverse temperature.
+--
+--   > let annealedTransition = anneal 0.30 (slice 0.5)
 anneal
   :: (Monad m, Functor f)
   => Double