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


-- | Stochastic gradient descent
--   
--   Implementation of a Stochastic Gradient Descent optimization method.
--   See examples directory in the source package for examples of usage.
--   
--   It is a preliminary implementation of the SGD method and API may
--   change in future versions.
@package sgd
@version 0.3


-- | Module provides data type for signed log-domain calculations.
module Numeric.SGD.LogSigned

-- | Signed real value in the logarithmic domain.
data LogSigned
LogSigned :: {-# UNPACK #-} !LogFloat -> {-# UNPACK #-} !LogFloat -> LogSigned

-- | Positive component
pos :: LogSigned -> {-# UNPACK #-} !LogFloat

-- | Negative component
neg :: LogSigned -> {-# UNPACK #-} !LogFloat

-- | Smart LogSigned constructor.
logSigned :: Double -> LogSigned

-- | Make LogSigned from a positive, log-domain number.
fromPos :: LogFloat -> LogSigned

-- | Make LogSigned from a negative, log-domain number.
fromNeg :: LogFloat -> LogSigned

-- | Shift LogSigned to a normal domain.
toNorm :: LogSigned -> Double

-- | Change the <a>LogSigned</a> to either negative <a>Left</a>
--   <a>LogFloat</a> or positive <a>Right</a> <a>LogFloat</a>.
toLogFloat :: LogSigned -> Either LogFloat LogFloat
instance Show LogSigned
instance Num LogSigned
instance NFData LogSigned
instance Ord LogSigned
instance Eq LogSigned


-- | Dataset abstraction.
module Numeric.SGD.Dataset

-- | A dataset with elements of type <tt>a</tt>.
data Dataset a
Dataset :: Int -> (Int -> IO a) -> Dataset a

-- | A size of the dataset.
size :: Dataset a -> Int

-- | Get dataset element with a given index. The set of indices is of a {0,
--   1, .., size - 1} form.
elemAt :: Dataset a -> Int -> IO a

-- | Lazily load dataset from a disk.
loadData :: Dataset a -> IO [a]

-- | A dataset sample of the given size.
sample :: RandomGen g => g -> Int -> Dataset a -> IO ([a], g)

-- | Construct dataset from a vector of elements and run the given handler.
withVect :: [a] -> (Dataset a -> IO b) -> IO b

-- | Construct dataset from a list of elements, store it on a disk and run
--   the given handler.
withDisk :: Binary a => [a] -> (Dataset a -> IO b) -> IO b

-- | Use disk or vector dataset representation depending on the first
--   argument: when <a>True</a>, use <a>withDisk</a>, otherwise use
--   <a>withVect</a>.
withData :: Binary a => Bool -> [a] -> (Dataset a -> IO b) -> IO b


-- | A gradient is represented by an IntMap from gradient indices to
--   values. Elements with no associated values in the gradient are assumed
--   to have a 0 value assigned. Such elements are not interesting: when
--   adding the gradient to the vector of parameters, only nonzero elements
--   are taken into account.
--   
--   Each value associated with a gradient position is a pair of positive
--   and negative components. They are stored separately to ensure high
--   accuracy of computation results. Besides, both positive and negative
--   components are stored in a logarithmic domain.
module Numeric.SGD.Grad

-- | Gradient with nonzero values stored in a logarithmic domain. Since
--   values equal to zero have no impact on the update phase of the SGD
--   method, it is more efficient to not to store those components in the
--   gradient.
type Grad = IntMap LogSigned

-- | Empty gradient, i.e. with all elements set to 0.
empty :: Grad

-- | Add normal-domain double to the gradient at the given position.
add :: Grad -> Int -> Double -> Grad

-- | Add log-domain, singed number to the gradient at the given position.
addL :: Grad -> Int -> LogSigned -> Grad

-- | Construct gradient from a list of (index, value) pairs. All values
--   from the list are added at respective gradient positions.
fromList :: [(Int, Double)] -> Grad

-- | Construct gradient from a list of (index, signed, log-domain number)
--   pairs. All values from the list are added at respective gradient
--   positions.
fromLogList :: [(Int, LogSigned)] -> Grad

-- | Collect gradient components with values in normal domain.
toList :: Grad -> [(Int, Double)]

-- | Perform parallel unions operation on gradient list. Experimental
--   version.
parUnions :: [Grad] -> Grad


-- | Stochastic gradient descent implementation using mutable vectors for
--   efficient update of the parameters vector. A user is provided with the
--   immutable vector of parameters so he is able to compute the gradient
--   outside of the IO monad. Currently only the Gaussian priors are
--   implemented.
--   
--   This is a preliminary version of the SGD library and API may change in
--   future versions.
module Numeric.SGD

-- | SGD parameters controlling the learning process.
data SgdArgs
SgdArgs :: Int -> Double -> Double -> Double -> Double -> SgdArgs

-- | Size of the batch
batchSize :: SgdArgs -> Int

-- | Regularization variance
regVar :: SgdArgs -> Double

-- | Number of iterations
iterNum :: SgdArgs -> Double

-- | Initial gain parameter
gain0 :: SgdArgs -> Double

-- | After how many iterations over the entire dataset the gain parameter
--   is halved
tau :: SgdArgs -> Double

-- | Default SGD parameter values.
sgdArgsDefault :: SgdArgs

-- | Vector of parameters.
type Para = Vector Double

-- | A stochastic gradient descent method. A notification function can be
--   used to provide user with information about the progress of the
--   learning.
sgd :: SgdArgs -> (Para -> Int -> IO ()) -> (Para -> x -> Grad) -> Dataset x -> Para -> IO Para