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


-- | Stochastic gradient descent
--   
--   Please see the README on GitHub at
--   <a>https://github.com/kawu/sgd#readme</a>
@package sgd
@version 0.2.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 GHC.Show.Show Numeric.SGD.LogSigned.LogSigned
instance GHC.Classes.Eq Numeric.SGD.LogSigned.LogSigned
instance GHC.Classes.Ord Numeric.SGD.LogSigned.LogSigned
instance Control.DeepSeq.NFData Numeric.SGD.LogSigned.LogSigned
instance GHC.Num.Num Numeric.SGD.LogSigned.LogSigned


-- | 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 version of parameters vector so he is able to compute the
--   gradient outside the IO/ST 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

-- | Dataset with elements of x type.
type Dataset x = Vector x

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

-- | Pure version of the stochastic gradient descent method.
sgd :: SgdArgs -> (Para -> x -> Grad) -> Dataset x -> Para -> Para

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