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


-- | Fast artifical neural networks
--   
--   Instinct is a library for fast artifical neural networks.
@package instinct
@version 0.1.0


-- | This module provides an efficient connection matrix type.
module AI.Instinct.ConnMatrix

-- | A connection matrix is essentially a two-dimensional array of synaptic
--   weights.
data ConnMatrix

-- | Build a layered connection matrix, where adjacent layers are fully
--   connected.
buildLayered :: [Int] -> IO ConnMatrix

-- | Build a completely random connection matrix with the given edge
--   length. The random values will be between -1 and 1 exclusive.
buildRandom :: Int -> IO ConnMatrix

-- | Build a zero connection matrix. It will represent a completely
--   disconnected network, where all nodes are isolated.
buildZero :: Int -> ConnMatrix

-- | Add two connection matrices. Note that this function is left-biased in
--   that it will adopt the connectivity of the first connection matrix.
--   
--   You may want to use the <a>Monoid</a> instance instead of this
--   function.
cmAdd :: ConnMatrix -> ConnMatrix -> ConnMatrix

-- | Strictly fold over the outputs, including zeroes.
cmDests :: Int -> (b -> Int -> Double -> b) -> b -> ConnMatrix -> b

-- | Strictly fold over the nonzero inputs of a node.
cmFold :: Int -> (b -> Int -> Double -> b) -> b -> ConnMatrix -> b

-- | Map over the inputs of a node.
cmMap :: (Int -> Int -> Double -> Double) -> ConnMatrix -> ConnMatrix

-- | Edge length of a connection matrix.
cmSize :: ConnMatrix -> Int

-- | <tt>addLayer s1 n1 s2 n2</tt> overwrite <tt>n1</tt> nodes starting
--   from <tt>s1</tt> to be fully connected with random weights to the
--   <tt>n2</tt> nodes starting from <tt>s2</tt>.
addLayer :: Int -> Int -> Int -> Int -> ConnMatrix -> IO ConnMatrix
instance Show ConnVector
instance Show ConnMatrix
instance Monoid ConnMatrix


-- | Activation functions.
module AI.Instinct.Activation

-- | Activation functions.
data Activation

-- | Logistic activation.
LogisticAct :: Activation

-- | Apply an activation function.
actFunc :: Activation -> Double -> Double

-- | Apply the derivative of an activation function.
actDeriv :: Activation -> Double -> Double
instance Read Activation
instance Show Activation


-- | This module provides artifical neural networks.
module AI.Instinct.Brain

-- | A <a>Brain</a> value is an aritifical neural network.
data Brain
Brain :: Activation -> ConnMatrix -> Int -> Int -> Brain

-- | Activation function.
brainAct :: Brain -> Activation

-- | Connection matrix.
brainConns :: Brain -> ConnMatrix

-- | Number of input neurons.
brainInputs :: Brain -> Int

-- | Number of output neurons.
brainOutputs :: Brain -> Int

-- | A signal pattern.
type Pattern = Vector Double

-- | Network builder configuration. See <a>buildNet</a>.
data NetInit

-- | Recipe for a multi-layer perceptron. This is a neural network, which
--   is made up of neuron layers, where adjacent layers are (in this case
--   fully) connected.
InitMLP :: Activation -> [Int] -> NetInit

-- | Network's activation function.
mlpActFunc :: NetInit -> Activation

-- | Layer sizes from input to output.
mlpLayers :: NetInit -> [Int]

-- | Build a random neural network from the given description.
buildNet :: NetInit -> IO Brain

-- | Pass the given input pattern through the given neural network and
--   return its output.
runNet :: Brain -> Pattern -> Pattern

-- | Convenience wrapper around <a>runNet</a> using lists instead of
--   vectors. If you care for performance, use <a>runNet</a>.
runNetList :: Brain -> [Double] -> [Double]

-- | Feeds the given input vector into the network and calculates the
--   activation vector.
activation :: Brain -> Pattern -> Vector Double

-- | Calculate the net input vector, i.e. the values just before applying
--   the activation function.
netInput :: Brain -> Pattern -> Vector Double

-- | Calculate the net input vector from the given activation vector.
netInputFrom :: Brain -> Vector Double -> Pattern -> Vector Double

-- | Construct a pattern vector from a list.
listPat :: [Double] -> Pattern

-- | The total discrepancy between the two given patterns. Can be used to
--   calculate the total network error.
patError :: Pattern -> Pattern -> Double
instance Read NetInit
instance Show NetInit
instance Show Brain


-- | Delta rule aka backpropagation algorithm.
module AI.Instinct.Train.Delta

-- | A training pattern is a tuple of an input pattern and an expected
--   output pattern.
type TrainPat = (Pattern, Pattern)

-- | Non-atomic version of <a>trainAtomic</a>. Will adjust the weights for
--   each pattern instead of at the end of the epoch.
train :: Brain -> Double -> [TrainPat] -> Brain

-- | Train a list of patterns with the specified learning rate. This will
--   adjust the weights at the end of the epoch. Returns an updated neural
--   network and the new total error.
trainAtomic :: Brain -> Double -> [TrainPat] -> Brain

-- | Train a single pattern. The second argument specifies the learning
--   rate.
trainPat :: Brain -> Double -> TrainPat -> Brain

-- | Calculate the weight deltas and the total error for a single pattern.
--   The second argument specifies the learning rate.
learnPat :: Brain -> Double -> TrainPat -> ConnMatrix

-- | Calculate the total error of a neural network with respect to the
--   given list of training patterns.
totalError :: Brain -> [TrainPat] -> Double

-- | Convenience function: Construct a training pattern from an input and
--   output vector.
tpList :: [Double] -> [Double] -> (Pattern, Pattern)


-- | Convenience module. Reexports the most important instinct modules.
module AI.Instinct