%%%%%%%%%%%%%%%%%%%%%%%%%%%begin%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The PANN Class Architecture}
%
The following UML figures visualize the class architecture
of the ANN prototype.
%
\vspace*{2cm}
\begin{center}
\begin{tabular}{|l|}
\hline
{\bfseries CANN\_ manager}\\
\hline
netlist : Vector of CANN\_ storage\\
functions : CANN\_ functiontable\\
learning : IANN\_ learningalg\\
compute : IANN\_ computation\\
flags : integer\\
\hline
CANN\_ manager\\
\~CANN\_ manager\\
createnet(list : CNVList) : integer\\
savenet\\
killNet(netno : integer) : boolean\\
killAllNets()\\
loadfun(fcnames : CNVList)\\
loadla(lcname : CNVList)\\
loadcalc(ccname : CNVList)\\
calcSingleNet(input : CNVList, netno : integer) : CNVList\\
calc(input : CNVList) : CNVList\\
learn(netno : integer) : boolean\\
\hline
\end{tabular}
\vspace*{1cm}
\end{center}

\begin{center}
\begin{tabular}{|l|}
\hline
{\bfseries CANN\_ storage}\\
\hline
no : integer\\
nodes : integer\\
bwmatrix : array[n][n] of double\\
flist : array[n] of integer\\
fdata : array[n] of Vector\\
value : array[n] of double\\
state : array[n] of integer\\
\hline
CANN\_ storage(n : integer)\\
set(what : integer, flag : integer) : boolean\\
is(what : integer, flag : integer) : boolean\\
unset(what : integer, flag : integer) : boolean\\
\hline
\end{tabular}

\vspace*{1cm}


\begin{tabular}{|l|}
\hline
{\bfseries CANN\_ actfunc} $\ll$abstract$\gg$\\
\hline
name : String\\
no : integer\\
\hline
CANN\_ actfunc\\
register(no : integer) : String\\
f(x : double, derivative : integer, fdata : Vector)\\
processFunctionData(fdata : Vector)\\
\hline
\end{tabular}

\vspace*{1cm}


\begin{tabular}{|l|}
\hline
{\bfseries CANN\_ functiontable}\\
\hline
nntable : Vector (name : string, fno : integer)\\
ftable : vector (CANN\_ actfunc)\\
\hline
load(classname : String) : integer\\
calc(fno : integer, x : double, derivative : integer, fdata : Vector) : double\\
n2n(fno : integer) : String\\
n2n(name : String) : integer\\
\hline
\end{tabular}

\vspace*{1cm}


\begin{tabular}{|l|}
\hline
{\bfseries IANN\_ computation}\\
\hline
fref : CANN\_ functiontable\\
annref : CANN\_ storage\\
\hline
calc(input : CNVList, net : CANN\_ storage) : CNVList\\
\hline
\end{tabular}

\vspace*{1cm}


\begin{tabular}{|l|}
\hline
{\bfseries IANN\_ learningalg}\\
\hline
learn(CANN\_ storage) : boolean\\
setDefaultParameters()\\
setParameters(parameters : CNVList)\\
\hline
\end{tabular}

\end{center}

\section{CANN\_ manager}
The class CANN\_ manager is the spine of the whole ANN class architecture. All communication with external
classes, such as agents, program manager and parameter manager, is handled via functions of this class.
The functions called from the program and parameter manager all have one single parameter of the type
CNVList, in order to ensure type compatibility. This approach also has the advantage that the content
of the CNVList is irrelevant to the manager classes, which as a result can handle unknown data from other
classes. There are only two functions with a different parameter format, namely
{\bfseries killNet(netno : integer) : boolean} and
{\bfseries calc(input : CNVList, netno : integer) : boolean}. The CNVList conventions used in our functions,
along with a brief description of the method's functionality.

\subsection{How to Read the CNVList Conventions}
Every entry if the list of of the following form:
\nvpair{name}{type}{further explanation e.g.:\\
Note that [n] must be replaced by a number, as described.
The name is case sensitive, and has to be interpreted
as a string (e.g.: nodes as ''nodes'', bias[n] as ''bias3'' or ''bias777'')\\
Note that counting always starts at zero ($0$).\\
nil is short for not in list}


\subsection{CNVList for CANN\_ manager.createNet}
The function {\bfseries createNet(list : CNVList) : integer} recieves an ANN stored in the CNVList,
creates the ANN in the CANN\_ storage class and returns the unique net-number. This number is needed
whenever an operation on the net is to be performed.

\subsubsection{NVPairs needed to create a net}

\nvpair{nodes}{INT}{number of nodes}
\nvpair{bias[n]}{DOUBLE}{Bias of node[n]\\
							value \ar bias\\
							nil   \ar 0 }

\nvpair{connection[f]:[t]}{DOUBLE}{Connection from node[f] to node[t].
							[f]=[t] would mean bias and is ignored!!\\
							value \ar weight\\
							0	  \ar no connection\\
							nil   \ar no connection }

\nvpair{function[n]}{STRING}{Name of activation function of node[n],
							nonexisting functions will be replaced by
							identity.\\
							value \ar function\\
							nil   \ar identity}							
							
\nvpair{funcdata[n]:[s]}{DOUBLE}{Function data for the function in node[n],
							the data must consist of double values.
							[s] is increased after a read, and if there
							is no [s+1] if [s] existed the attempt to read
							is stopped. If there is no funcdata[n]:0 then
							the vector for this function is empty.\\
							value \ar included in function data vector\\
							nil	  \ar stop reading.}

\nvpair{initvalue}{DOUBLE}{Initial output value of all nodes, in case there
							are loops.\\
							value \ar value\\
							nil	  \ar 0}

\nvpair{inert[n]}{BOOLEAN}{With this option certain nodes can be set to
							inert; inert nodes will be ignored (even by
							calculation). See also \ref{ac}\\
							value \ar node[n] is inert\\
							nil   \ar node[n] is active}

\nvpair{input[n]}{BOOLEAN}{Set nodes as input nodes. See also \ref{ac}\\
							value \ar node[n] is input node\\
							nil   \ar nothing changes for node[n]}

\nvpair{output[n]}{BOOLEAN}{Set nodes as output nodes. See also \ref{ac}\\
							value \ar node[n] is output node\\
							nil   \ar nothing changes for node[n]}

\subsubsection{About Autochecks}
\label{ac}
There are autochecks for input and output neurons included, but they are
switched off if user definitions are given:
\begin{center}
\begin{tabular}{l|ccc}
user & \multicolumn{3}{c}{autocheck}\\
defined &input &output &inert\\
\hline
input  &off &    &off\\
output &    &off &off\\
inert  &    &off &
\end{tabular}
\end{center}
Short description of check algos:
\begin{center}\begin{tabular}{l@{ \ar }l}
no incoming connections& input\\
no outgoing connections& output\\
input and output&        inert
\end{tabular}\end{center}

\subsection{NVPairs used in CANN\_manager.calc}
The function {\bfseries calc(input : CNVList) : CNVList} computes output vector of all ANNs
to given input vectors. The CNVList input and the list returned by the function
contain the following tags:

\nvpair{[netno]input[n]}{DOUBLE}{Define DOUBLE as the n-th input for the net with number netno.}						
\nvpair{[netno]output[n]}{DOUBLE}{Define DOUBLE as n-th output of the net with number netno.}						



\subsection{NVPairs used in CANN\_manager.loadfun}
The function {\bfseries loadfun(fcnames : CNVList) : integer} loades the activation functions with the
classnames stored in fcnames and returns the number of succesfully loaded functions.

\nvpair{activation function[n]}{STRING}{Load activation function with classname STRING. Note that
                                          [n] must run from $0$ to $m-1$ to load all m functions.}						
							
\subsection{NVPairs used in CANN\_manager.loadcalc}
The function {\bfseries loadcalc(ccname : CNVList) : boolean} loades the computation algorithm with the
classname stored in ccname and returns true if successful, false otherwise. If loading the class fails,
a default computation class is used.

\nvpair{calc classname}{STRING}{Load computation class with classname STRING.}						

\subsection{NVPairs used in CANN\_manager.loadla}
The function {\bfseries loadla(lcname : CNVList) : boolean} loades a learning algorithm with the
classname stored in lcname and returns true if successful, false otherwise. Note that there is no default
learning algorithm, causing calls of CANN\_ manager.learn to be useless. The CNVList lcname may also contain
data that is to be passed on to the learning algorithm.

\nvpair{la classname}{STRING}{Load learning class with classname STRING.}						


\section{CANN\_ functiontable}
\subsection{Error Handling in CANN\_ functiontable}
Numerous errors can arise in CANN\_ functiontable. To guarantee that small errors do not terminate an entire run, none of the errors
that may typically arise stop the program, but are commented on System.err once, and them avoided. This means that if a certain
activation function can not be loaded, type casted to CANN\_ actfun and registered, the identity function (''identity.java''),
which is loaded at the instanciation of the class, is used instead. If the constructor fails to load the identity, all
functions that cannot be loaded succesfully are set to constant zero ($f(x)=0$).

\section{CANN\_ actfun}
\subsection{How to Implement a New Activation Function}
All activation functions have to be derived from the abstract class CANN\_ actfun. The constructor of the new activation
function must set the name variable to the name of the function (it's a good idea to set it identical to the classname,
but without ''.java'' or ''.class''). \\
The function f(double x, int derivative, Vector fdata) contains the expression or
algorithm for the computation of the function's value at x, to a given derivative (if necessary for the used learning
algorithm). The Vector fdata contains special function data from the CANN\_ storage class, for the implementation of
special activation functions (such as splines). The function register(int fno) is a built in function that stores the
internal function number and returns name.\\
Functions that require processed function data have to implement the function processFunctionData(fdata : Vector). This
function is executed once for every neuron at the net initialization. Note that the implementation of this
function is optional, the abstract class CANN\_ actfun contains a non-abstract version of this function, that
leaves fdata unchanged.

\subsection{The Activation Function 'SplineFunction'}
This activation function computes the value of a cubic function, that is interpolated through a series of points.
The interpolation is done with the following condition.\\
Let $(x_{1},y_{1}) .. (x_{n},y_{n}) \in R^{2}$ be a series of points. Then the coefficients of a function $f_{i}, 0 \leq i \leq (n-3)$
(one function for every three points) are obtained by solving the following linear equation system:
$$ f_{i}(x_{i}) = a_{i} x_{i}^3 + b_{i} x_{i}^2 + c_{i} x_{i} + d_{i} = y_{i},$$
$$ f_{i}(x_{i+1}) = a_{i} x_{i+1}^3 + b_{i} x_{i+1}^2 + c_{i} x_{i+1} + d_{i} = y_{i+1},$$
$$ f_{i}(x_{i+2}) = a_{i} x_{i+2}^3 + b_{i} x_{i+2}^2 + c_{i} x_{i+2} + d_{i} = y_{i+2},$$
$$ f_{i}'(x_{i}) = 3 a_{i-1} x_{i}^2 + 2 b_{i-1} x_{i} + c_{i-1} = 3 a_{i} x_{i}^2 + 2 b_{i} x_{i} + c_{i} = f_{i-1}'(x_{i}).$$
Note that $ a_{0} = b_{0} = c_{0} = 0 = f_{0}'(x)$ $\forall x \in R$.
Outside of the interval defined by $[x_{0},x_{n}]$ the function is constant and equals $y_{0}$ and $y_{n}$ respectively. \\
Problems that could make an interpolation impossible, such as $x_{i} = 0$ or problematic ratios, such as $\frac{x_{i}^3}{3 x_{i + k}^2} = \frac{x_{i}^2}{2 x_{i + k}}, 1 \leq k \leq 2$
are resolved by adding a value delta to the unsuitable $x_{j}$.
%%%%%%%%%%%%%%%%%%%%%%%end%%%%%%%%%%%%%%%%%%%%%
