---------------------------------------------------------
-- |
-- Module     :  AI.Network
-- License    :  GPL
--
-- Maintainer :  Kiet Lam <ktklam9@gmail.com>
--
--
-- This module provides the signatures for needed
-- functions in a neural network
--
--
---------------------------------------------------------


module AI.Signatures (
  ActivationFunction,
  DerivativeFunction,
  ErrorFunction,
  CostFunction,
  CostDerivative,
  GradientFunction
  ) where

import Data.Packed.Matrix
import Data.Packed.Vector

import AI.Network


-- | Type that represents the activation function
type ActivationFunction = Double -> Double


-- | Type that represents the derivative of the activation function
--
-- NOTE: The derivative can be non-trivial and must be continuous
type DerivativeFunction = Double -> Double


-- | Type that represents the error function
-- between the calculated output vector
-- and the expected output vector
type ErrorFunction = Vector Double     -- ^ The calculated output vector
                     -> Vector Double  -- ^ The expected output vector
                     -> Double         -- ^ Returns the error of how far off
                                       --   the calculated vector is from the
                                       --   expected vector


-- | Type that represents the function
-- that can calculate the total cost of the neural networks
-- given the neural networks, the input matrix and an expected output matrix
type CostFunction = Network          -- ^ The neural networks of interest
                    -> Matrix Double -- ^ The input matrix, where the ith row
                                     --   is the input vector of a training set
                    -> Matrix Double -- ^ The expected output matrix, where the
                                     --   ith row is the expected output vector
                                     --   of a training set
                    -> Double        -- ^ Returns the cost of the calculated output vector
                                     --   from the neural network and the given
                                     --   expected output vector


-- | Type that represents the cost function derivative.
-- on the output nodes
type CostDerivative = Network          -- ^ The neural networks of interest
                      -> Matrix Double -- ^ The matrix of inputs where the ith row
                                       --   is the ith training set
                      -> Matrix Double -- ^ The matrix of calculated outputs where the
                                       --   ith row is the ith training set
                      -> Matrix Double -- ^ The matrix of expected outputs where the
                                       --   ith row is the ith expected output of
                                       --   of the training set
                      -> Matrix Double -- ^ Returns the matrix of the derivatives
                                       --   of the cost of the output nodes
                                       --   compared to the expected matrix


-- | The type to represent a function that
-- can calculate the gradient vector
-- of the weights of the neural network
--
-- NOTE: Must be supplied a function to calculate the cost, the
-- cost derivative of the output neurons, the neural network
-- the input matrix, and the expected output matrix
type GradientFunction = CostFunction      -- ^ The cost function
                        -> CostDerivative -- ^ The cost derivative
                        -> Network        -- ^ The neural network
                        -> Matrix Double  -- ^ The input matrix
                        -> Matrix Double  -- ^ The expected output matrix
                        -> Vector Double  -- ^ Returns the gradient vector
                                          --   of the weights