```---------------------------------------------------------
-- |
-- 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,
) 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
```