userext.tex

basic.c */ /**//* Project:NeuroBasic, basic package*//**/ /* Survey:This is a simple Basic b-code

%======================

Neuro-objects are defined with a C structure which contains
information about the object itself and pointers to the object-data
(\eg layers, weight matrices, etc.). All neuro-object structures are
united in a union called {\tt neuro\_obj\_t}. An array of these unions
called {\tt neuro\_objs}, finally, holds the actual neuro-objects.

The following example structure defines a layer for the
back-propagation algorithm.

\begin{verbatim}
  typedef struct
  {
    MFLOAT      *poutp;         /* pointer to output vector */
    MFLOAT      *pdelta;        /* pointer to error vector */
    comm_def_t  window;         /* communication window */
  } layer_t;                    /* general layer */
\end{verbatim}

\noindent In this case, the communication window contains all
necessary information about the layer, like its size and partitioning
among the processing elements.
  
To create a new neuro-object type, the programmer has to put the
corresponding type definition into the file {\tt nobjs.h} of the local
subdirectory of the package it belongs to. The global makefile
then calls the utility program {\tt mknobjs} which reads the {\tt
nobjs.h} files of all subdirectories and creates the file {\tt
basic/allnobjs.h} which contains the union {\tt neuro\_obj\_t}. Each 
C module which works with neuro-objects must include this header
file.

Note that the size of a neuro-object type is limited to 160 bytes
({\tt MINT}s and {\tt MFLOAT}s both need 4 bytes per value). Note also
that one communication window ({\tt comm\_def\_t}) already needs 72
bytes.

In order to recognize neuro-objects {\tt mknobjs} assumes that the
corresponding structure names end with the letters ``{\tt \_t}''. It
drops these two letters when creating the corresponding object-name in
the union. The following example shows the union for containing the
above layer-type.

\begin{verbatim}
  typedef union
  {
        .
        .
    layer_t layer;
        .
        .
    public_t public;
  } neuro_obj_t;
\end{verbatim}

\noindent Let's assume that element 3 in the {\tt neuro\_objs} array
is of our layer type and we want to access the fifth element of the
output layer. The corresponding C expression to do this is

\begin{verbatim}
  neuro_objs[3].layer.poutp[4]
\end{verbatim}


\noindent The structure {\tt public\_t} is the largest type of the
union and determines its size. It reserves 160 byte at the top ({\tt
filler}) and defines afterwards variables for public information for
the neuro-objects. The reserved space at the top is to store the
information of the other neuro-object types. The {\tt public\_t} is
defined as follows:

\begin{verbatim}
  typedef struct
  {
    MINT filler[40];
    MINT obtype;
    MINT trans_buf_size;
    void (*fn_release)(MINT nobj);
    MINT (*fn_load)(MINT nobj);
    MINT (*fn_save)(MINT nobj);
    MINT (*fn_nput)(MINT nobj, MINT nx, MINT ny, MFLOAT value);
    MFLOAT (*fn_nget)(MINT nobj, MINT nx, MINT ny);
    MINT (*fn_rand)(MINT nobj, MFLOAT range);
  } public_t;
\end{verbatim}

\noindent The structure elements have the following meaning:

\begin{fctitem}{obtype}
Each neuro-object type has a unique number to be recognized as
such. It is stored in this variable. The {\tt mknobjs} program creates
a macro for each object type and writes it to the file {\tt
basic/allnobjs.h} (together with the neuro-object definitions). The
macro names are the capitalized object names preceded by the string
{\tt N\_}. The type number of the {\tt layer\_t}, for instance, would
be {\tt N\_LAYER}.

The number 0 is assigned to the predefined macro {\tt N\_FREE} to
mark an element of the neuro-object list as unused.
\end{fctitem}

\begin{fctitem}{trans\_buf\_size}
This is the minimum size of the transfer buffer (see 
Section~\ref{sec_transbuf}) used by this object. This variable is
internally used and must not be changed by the user.
\end{fctitem}

\begin{fctitem}{(*fn\_release)(MINT nobj)}
This is a pointer to the release function of the neuro-object,
\ie a function which frees all the allocated space of the object
and marks the object as unused by writing {\tt N\_FREE} into the
object type.
\end{fctitem}

\begin{fctitem}{(*fn\_load)(MINT nobj)}
This is a pointer to the {\em load\/} function of the object. It will
be executed when the {\tt load()} function is called for this
object from the Basic interpreter.
n\end{fctitem}

\begin{fctitem}{(*fn\_save)(MINT nobj)}
This is a pointer to the {\em save\/} function of the object. It will
be executed when the {\tt save()} function is called for this
object from the Basic interpreter.
\end{fctitem}

\begin{fctitem}{(*fn\_nput)(MINT nobj, MINT nx, MINT ny,
MFLOAT value)} This is a pointer to the {\em put\/} function of the
object. It will be executed when the {\tt nput()} function is called
for this object from the Basic interpreter.
\end{fctitem}

\begin{fctitem}{(*fn\_nget)(MINT nobj, MINT nx, MINT ny)}
This is a pointer to the {\em get\/} function of the object. It will
be executed when the {\tt nget()} function is called for this
object from the Basic interpreter.
\end{fctitem}

\begin{fctitem}{(*fn\_rand)(MINT nobj, MFLOAT range)}
This is a pointer to the {\em randomize\/} function of the object. It
will be executed when the {\tt randomize()} function is called for
this object from the Basic interpreter.
\end{fctitem}

\noindent All except the release function are voluntary. If they
don't exist for a certain object then the corresponding pointer
must be {\tt NULL}.

The following example C sequence tests if object 3 is of
{\tt layer\_t} and, if yes, assigns the width of the layer from
its communication window to the variable {\tt width}.

\begin{verbatim}
  if (neuro_objs[3].public.type == N_LAYER)
  {
    width = neuro_objs[3].layer.window.dim.x;
  }
\end{verbatim}



\subsection{Create Neuro-Objects}
\index{create neuro-objects}
%--------------------------------

For each neuro-object type there must be a neuro-function to create
objects of its type. These functions usually start with the letters
{\tt new\_} and end with the name of the object, \eg {\tt
new\_layer()} to create a new layer. The following steps have to be
taken by the creator function:

\begin{enumerate}
\item Get the index of a free entry in the neuro-object list. This is
  done by calling the function {\tt alloc\_nobj(tbsize)}
  \index{alloc\_nobj@{\tt alloc\_nobj()}}. It returns the index or a
  negative number if the object table is full. The parameter {\tt
  tbsize} specifies the maximum space which the object ever will use
  in the transfer buffer (see Section~\ref{sec_transbuf}) when
  communicating its data. {\tt tbsize} is the number of machine
  words. For 100 floating-point values, for instance, this would be
  {\tt 100 * sizeof(MFLOAT)}.\\ In cases where it is necessary to
  resize the transfer buffer, NeuroBasic provides the function {\tt
  realloc\_nobj(nobj, tbsize)} 
  \index{realloc\_nobj@{\tt realloc\_nobj()}}. It sets the transfer
  buffer size of the neuro object {\tt nobj} to the size {\tt tbsize}.

\item Allocate the necessary memory space for the object and set
  the pointers and other object specific variables accordingly.

\item Set the object type to indicate that the object is no longer
  free.

\item Set the pointers to the release, load, save, nput and nget
  function of this object. The release function is mandatory. The
  others can be replaced by {\tt NULL} if not available.

\item Return the index of the new object.
\end{enumerate}


\noindent The {\em release function\/} has to free all memory space
which was allocated for the object and then call {\tt free\_nobj(nobj)}
to delete the object from the object table. The release function will
get the index of the neuro-object as parameter and its return value
will be passed to the Basic interpreter. The prototype of a release
function is

\bigskip {\tt MINT {\em functionname}(MINT nobj);}




\subsection{Load Functions}
\index{load functions}
%--------------------------

Because a function running on \MUSIC\ cannot access the file system of
the host computer, the file handling is done by the host part of
NeuroBasic. A load function just has to receive the data from the
host and store it at the right places of its neuro-object. The
prototype of a load function is

\bigskip {\tt MINT {\em functionname}(MINT nobj);}

\bigskip\noindent {\tt nobj} is the index of the object into which the
data has to be loaded. The return value of the function is passed to
the Basic interpreter.

A load function first has to call the function {\tt setup\_load()}
\index{setup\_load@{\tt setup\_load()}} which passes the expected
  dimensions of the data to the host: 

\bigskip {\tt MINT setup\_load(ndim, xdim, ydim, zdim, block\_size,
                               format);}

\bigskip\noindent {\tt ndim} is the number of dimensions of the matrix
(up to 3) followed by the three dimensions {\tt xdim}, {\tt ydim} and
{\tt zdim}. An unused dimension (\eg {\tt zdim} when {\tt ndim}~=~2)
has to be set to 1. The meaning of the individual dimensions is object
dependent and has to be coordinated among the neuro-functions
themselves which work with the object.

{\tt block\_size} is the size of the data which will be
received in one block from the host. It can be set to {\tt xdim * ydim
* zdim} if the complete data set will be loaded in one step. Note that
the dimensions of a data block sent over the \MUSIC\ communication
network are restricted in size which sometimes naturally splits the
loading of a large data set in several blocks. The {\tt block\_size} is
the same throughout the complete loading procedure.

{\tt format} indicates the format of the data to be loaded. It is
always floating-point ({\tt FF\_FLOAT32}). The only exception are
training patterns which can load data in the compact fixed-point
format ({\tt FF\_FIXED8}) to save memory space on \MUSIC.

The {\tt setup\_load()} function returns 0 ({\tt FALSE}) if the
loading process cannot be carried out. This is the case, for instance,
when expected data dimensions for the neuro-object are not the same as
stored on the file. In all other cases the function returns a nonzero
value ({\tt TRUE}).

To receive the actual data from the host computer either the {\tt
Rd\_from\_host()} function can be called or a normal communication can
be carried out with {\tt HOST\_IO} as the producer (see \MUSIC\
Tutorial).




\subsection{Save Functions}
\index{save functions}
%--------------------------

A save function is the same as a load function except that the data is
passed in the other direction, \ie from the \MUSIC\ to the host, which
will save it on disk. Again, the file handling is carried out by the
host part of NeuroBasic and a save function just has to send the data
of the desired object to the host. The prototype of a save function is

\bigskip {\tt MINT {\em functionname}(MINT nobj);}

\bigskip\noindent {\tt nobj} is the index of the object which
has to be stored on disk. The return value of the function is passed to
the Basic interpreter.

A save function first has to call the function {\tt setup\_save()}
\index{setup\_save@{\tt setup\_save()}} which passes the dimensions of
the data to the host: 

\bigskip {\tt MINT setup\_save(ndim, xdim, ydim, zdim, block\_size);}

\bigskip\noindent {\tt ndim} is the number of dimensions of the matrix
(up to 3) followed by the three dimensions {\tt xdim}, {\tt ydim} and
{\tt zdim}. An unused dimension (\eg {\tt zdim} when {\tt ndim}~=~2)
has to be set to 1. The meaning of the individual dimensions is object
dependent and has to be coordinated among the neuro-functions
themselves which work with the object.

{\tt block\_size} is the size of subblocks which will be sent to the
host in several steps. It can be set to {\tt xdim * ydim * zdim} if
the complete data set will be sent in a single step. Note that the
dimensions of a data block sent over the \MUSIC\ communication network
are restricted in size which sometimes naturally splits the saving of
a large data set in several blocks. The {\tt block\_size} is the same
throughout the complete saving procedure.

The {\tt setup\_save()} function returns 0 ({\tt FALSE}) if the saving
process cannot be carried out, for instance, if there is not enough
space on the disk to store the data. In all other cases the function
returns a nonzero value ({\tt TRUE}).

To sent the actual data to the host computer either the {\tt
Wr\_to\_host()} function can be called or a normal communication can
be carried out with {\tt HOST\_IO} as the consumer (see \MUSIC\
Tutorial).




\subsection{Put Functions}
\index{put functions}
%-------------------------

A put function has to receive a single value from the host and has to
store it at the right place of an object. The prototype of a put
function is

\bigskip {\tt MINT {\em functionname}(MINT nobj, MINT i, MINT j,
                                      MFLOAT value);}

\bigskip\noindent {\tt nobj} is the index of the object, {\tt i} and
{\tt j} are ``coordinates'' which indicate the element in the object
where {\tt value} has to be put. The coordinates $i$ and $j$ are what
ever the user types in when calling {\tt nput()}. Their interpretation
is up to the put function itself. See the description of some
neuro-objects in the previous chapters for examples.

The return value of the put function is passed back to the Basic
interpreter.



\subsection{Get Functions}
\index{get functions}
%-------------------------

A get function is the opposite of a put function. It has to return the
value of a specified element of an object. The prototype of a get
function is

\bigskip {\tt MFLOAT {\em functionname}(MINT nobj, MINT i, MINT j);}

\bigskip\noindent {\tt nobj} is the index of the object, {\tt i} and
{\tt j} are ``coordinates'' which indicate the element in the object
which has to be returned. The coordinates $i$ and $j$ are what ever
the user types in when calling {\tt nput()}. Their interpretation is
up to the get function itself. See the description of some
neuro-objects in the previous chapters for examples.