userext.tex

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

\subsection{Randomize Functions}
\index{randomize functions}
%-------------------------------

A randomize function is to fill the data of a neuro-object, \eg a
weight set, with random data within a certain range. The prototype of
a randomize function is

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

\bigskip\noindent {\tt nobj} is the index of the object and {\tt
range} is the range for the random numbers. It usually means that
random numbers within ({\tt -range...+range}) will be
produced.
\index{neuro-objects|)}




\section{Symbolic Constants}
\index{symbolic constants|textbf}
%================================

Symbolic constants are macros ({\tt \#define ...}) defined in the file
{\tt nobjs.h}. The make file will put them into the global header file
{\tt allnobjs.h} and will also produce corresponding interface code
(in the file {\tt bconst.c}) to make these macros visible from the
Basic interpreter. Thus, symbolic constants can be used from both
sides, the Basic interpreter and all C source files. An example are
the file format constants ({\tt FLOAT}, {\tt FIXED} and {\tt ASCII}).




\section{Host-Functions}
\index{host-functions|(}
%=======================

Each \MUSIC\ system is attached to a host computer (see \MUSIC\
Tutorial). So far we were talking only about code which runs on the
\MUSIC\ side. Sometimes it is also necessary to write code on the host
side. Most NeuroBasic programmers, however, never need to do
this. Thus, read this section only if you really need to write code on
the host side, for instance, if you want to load data of a file format
which is different from the NeuroBasic formats. The mechanism is
simple. The programmer needs to write functions on the host side which
are later called (remote) by neuro-functions which are running on the
\MUSIC\ side.



\subsection{Register Host-Functions}
%-----------------------------------

To make user-defined host functions available for neuro-functions,
their prototype must be defined in a header file named {\tt hfcts.h}
\index{hfcts.h@{\tt hfcts.h}} of the local subdirectory, similar as
the prototypes of neuro-functions are defined in a file named {\tt
nfcts.h}. Note, however, that host-functions, in contrast to
neuro-functions, are {\em not\/} ``visible'' from the Basic
interpreter. They are for ``internal use'' of neuro-functions only.
If no file named {\tt hfcts.h} exists in a package, the global make
file will create one of that name with length zero.

The global makefile \index{makefile!global} will collect the
prototypes of the files {\tt hfcts.h} of all packages and create the
files {\tt allhfcts.h} and {\tt hostif.c} in the {\tt basic}
subdirectory. The file {\tt allhfcts.h} has to be included by both,
modules on the host and on the \MUSIC\ side which communicate with
each other. This file contains prototypes of all host-functions and a
type {\tt enum} which assigns to each host-function a number. This
number will be used to call the specific function from the \MUSIC\
side.



\subsection{The Message Buffer}
\index{message buffer}
%------------------------------

To exchange information between the host and the \MUSIC\ side a
specific data type, called \index{message buffer} {\em message
buffer}, is used. It's name is {\tt message\_t} and it is defined in
\index{message\_t@{\tt message\_t}} the file {\tt common.h} of the {\tt
basic} package. This file will automatically be included by the file
{\tt allhfcts.h}. The message buffer is an array of 10 32-bit
words. Each array entry is a union which can either be an integer, a
floating-point value, or a pointer. The definition of the message
buffer is as follows:

\begin{verbatim}
  typedef union
  {
    MINT        i;
    MFLOAT      f;
    void        *p;
  } message_t[10];
\end{verbatim}



\subsection{Calling Host-Functions from the MUSIC Side}
%------------------------------------------------------

When a Basic program is executed on the \MUSIC\ side, the host waits,
in a so-called server loop, for messages coming from the \MUSIC\ side.
In order to call a host function from the \MUSIC\ side a variable of
type {\tt message\_t} has to be allocated and sent to the host. The
following C example calls an imaginary function named {\tt
host\_demo()} on the host side.

\begin{verbatim}
  message_t msg;

  msg[0].i = C_USER_FCT;        /* call a user-defined host-function */
  msg[1].i = HOST_DEMO;         /* number of the host-function */
  msg[2].i = ...                /* function specific data follows */
  msg[3].f = ...
  Wr_to_host(msg, sizeof(msg), WR_ONE); /* send message to host */
\end{verbatim}

\noindent As can been seen from the example, the first entry of the
message buffer must contain a code, defined by the macro {\tt
C\_USER\_FCT}, \index{C\_USER\_FCT@{\tt C\_USER\_FCT}} to inform the
server loop that a user-defined host function should be called. The
second entry of the message buffer must contain the number of the
desired host-function.  The macro {\tt HOST\_DEMO} was automatically
created by the global make file and put into the header file {\tt
allhfcts.h}. It is the name of the host-function in capital letters.



\subsection{Host-Function Definition}
%------------------------------------

The host function itself will receive a pointer to the message buffer
sent from the \MUSIC\ side as a parameter. Host-functions may not have
return values (the return type must be {\tt void}). The following is
an example of the host-function used by the previous section.

\begin{verbatim}
  void host_demo(message_t msg)
  {
    ...                 /* code of host-function follows */
  }
\end{verbatim}

\noindent The host-function can do whatever needs to be done using the
function specific data of the message buffer, starting at element 2.
In particular, the host and \MUSIC\ side can exchange more data using
the data transfer mechanisms of the \MUSIC\ operating system (see
\MUSIC\ Tutorial).

Examples for the host calling mechanism are, for instance, the
neuro-functions {\tt load()} and {\tt save()} in the file {\tt
basic/neurolib.c} with their counterparts {\tt basic\_load()} and
{\tt basic\_save()} in {\tt basic/host.c} on the host side.
\index{host-functions|)}



\subsection{Files}
%-----------------

The following is a summary of the files involved in the host calling
mechanism.

\begin{list}{}{\renewcommand{\makelabel}[1]{\tt#1}}
\item [hfcts.h] is defined by the programmer in the local subdirectory
  of a package and contains the prototypes of all user-defined host
  functions.  If no file of this name exists, then the global makefile
  will create one of length zero.
\item [allhobjs.h] is created by the global makefile in the {\tt
    basic} subdirectory. It contains all host-function prototypes and
  the enumeration of the host functions which are the names of the
  host-functions in capital letters.
\item [hostif.c] is created by the global make file and contains a
  list of pointers to all host-functions. It can be ignored by
  programmers.
\end{list}




\section{Documentation}
\index{documentation}
%======================

The NeuroBasic documentation is done with the \LaTeX\ typesetting
system. Each package has to have its own documentation \LaTeX\ source
in the local file {\tt manual.tex}. It is up to the programmer what to
put into the documentation of a package. Just a few rules have to be
followed.

\begin{itemize}
\item The {\em report} style is used for the documentation. This means
  that the sectioning starts with {\tt $\backslash${}chapter} and then
  continues with {\tt $\backslash${}section} and {\tt
  $\backslash${}subsection}. The general rule is to have one chapter
  per package in the documentation.

\item There is a special macro, called {\tt nfunction}, for the
  description of neuro-functions which can best be described with an
  example. The source text
  \begin{verbatim}
    \begin{nfunction}{animal}{size, weight}
    The function {\tt animal} is just an example. It takes {\tt size}
    and {\tt weight} as parameter.
    \end{nfunction}
  \end{verbatim}
  produces the following output.
  \begin{nfunction}{animal}{size, weight}
  The function {\tt animal} is just an example. It takes {\tt size}
  and {\tt weight} as parameter.
  \end{nfunction}
  
  It is highly recommended to use this macro, once because then all
  function description in the manual look optically alike and also
  because a future on-line help in NeuroBasic then can recognize the
  descriptions of neuro-functions by looking for that macro. The
  macro also automatically generates an index entry for the function.
\end{itemize}

\noindent As mentioned before the global make file will collect the
{\tt manual.tex} files from all packages and merge them to a complete
NeuroBasic documentation.



\section{The Local Makefile}
\index{makefile!local}
%===========================

The local makefile must contain the following targets:

\begin{list}{}{
\setlength{\parsep}{0em}
\setlength{\itemsep}{0em}
\setlength{\leftmargin}{4.5em}
\setlength{\labelwidth}{4em}
\setlength{\labelsep}{0.5em}    % \leftmargin - \labelwidth
\renewcommand{\makelabel}[1]{\tt#1\hfil}
}
\item[local:] the file {\tt local.o} must be generated which is the
 local version of its code.
\item[music:] the file {\tt music.cln} must be generated which is the
  \MUSIC\ version of its code.
\item[sim:] The file {\tt ssim.o} must be generated which is the
  simulator version of its code.
\item[backup:] A backup of all source files (including documentation
  and the makefile) of the package must be produced.
\end{list}


\paragraph{Warning!} Note that the cross compiler which is used to
generate code for the \MUSIC\ computer, {\em g96k}, marks its local
labels only with the name of the source file but not with the
path. The consequence is that in the complete NeuroBasic environment,
including all packages, no two C source files can have the same
name. If it is the case, then the global link phase of {\em g96k\/}
will report dozens of errors about duplicate symbols.




\chapter{Writing Data-Parallel Code}
\index{data-parallel code}
\label{sec_dataparallel}
%***********************************

The \MUSIC\ system is a distributed-memory supercomputer which is
programmed in the {\small SPMD} mode (Single Program Multiple
Data). This means that the same program runs individually on each
processing element using only local program and data memory. The main
difference to a {\small SIMD} machine (Single Instruction Multiple
Data) is that each processor can take different pathes of the program
at runtime without dropping the performance.

The normal way to program the \MUSIC\ computer is to let each of the
processing elements produce a different part of a certain data set
(\eg a layer of neurons). After that the communication network
(realized in hardware) collects and redistributes the data. The
programmer does not have to consider where to send the data and where
from to receive it. The only things the communication network needs to
know are the dimensions of the data set (up to three dimensions are
supported), which part was produced on a particular processing element
and which other part should be received by it.

The information about which part of the output will be produced on a
certain processing element and which other part it will receive is
stored n a structure of the type {\tt comm\_def\_t}, also called {\em
window}.

In order to write parallel code for the \MUSIC\ system the programmer
should be familiar with the \MUSIC\ programming environment. The
necessary information is provided in the \MUSIC\ Tutorial. This
chapter provides some additional information in connection with
writing \MUSIC\ code in the NeuroBasic environment.



\section{The Transfer Buffer}
\index{transfer buffer|(}
\label{sec_transbuf}
%============================

When the data of a certain neuro-object, for instance a layer, is
computed each processing element writes its output into a temporary
local buffer. From there it is picked up by the communication network
and distributed to its final destinations on the different processing
elements. In case of the layer, each processing element will receive a
copy of the complete layer, which is needed as input to compute the
output of a following layer.\footnote{A good overview of the \MUSIC\
back-propagation \index{back-propagation} implementation is given in
the paper {\em High Performance Neural Net Simulation on a
Multiprocessor System with ``Intelligent'' Communication} by Urs
A. M\"uller, Michael Kocheisen and Anton Gunzinger in Advances in
Neural Information Processing Systems 6 (NIPS*93), pp. 888--895,
Morgan Kaufmann Publishers, 1994 or in the paper {\em Achieving
Supercomputer Performance for Neural Net Simulation with an Array of
Digital Signal Processors} by Urs A. M\"uller, Bernhard B\"aumle,
Peter Kohler, Anton Gunzinger and Walter Guggenb\"uhl in the {\small
IEEE} Micro Magazine, vol.~12, no.~5, pp. 55--65, 1992.}

Communication and computation on the \MUSIC\ system are independent
and can therefore overlap in time. This means that while the result of
one function is being communicated, another function can already
start computing.

In order to allow the overlapping of communication and computation
between different neuro-functions without being visible from the Basic
shell, the neuro-functions have to obey the following principle:

\begin{enumerate}
\item A neuro-function computes its subset of the data and writes it
  into a temporary buffer.

\item It then starts the communication network which picks up the
  data from that buffer and distributes it to the final destination
  (normally a neuro-object). The function returns without waiting for
  the end of the current communication phase.

\item The following neuro-function will start with its computation
  while the communication of the previous function is still
  ongoing. It will only wait for the end of the present communication
  phase if it needs the data that is being communicated or if it needs
  the communication network itself.
\end{enumerate}

\noindent This requires the programmer of neuro-functions to obey
certain regulations in order to obtain a correct data flow. The key
point is the {\em transfer buffer}, named {\tt trans\_buf}. It is
actually a structure, pointing to the two different buffers 0 and 1,
large enough to hold data parts of any neuro-object. The transfer
buffer is used for the following:

\begin{itemize}
\item One of the buffers contains the data which is currently being
  sent to the communication network and the other one is filled with
  new data produced by the current neuro-function.