userext.tex

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

% *******************************************************************
%
% File:         userext.tex
%
% Survey:       NeuroBasic, Part of the Reference Manual
%
% Author:       Urs Mueller
%               Electronics Laboratory, ETH Zuerich,
%               Switzerland
%
% Created:      July 20, 1994
% Modified:     November 29, 1994 (um)
%
% *******************************************************************




\chapter{User Extensions}
%************************

This chapter describes how a programmer can extend the NeuroBasic
simulator with own neuro-functions. The reader should have a good
knowledge of the C\index{C programming language} programming
language\footnote{A good reference to the C programming language is
Brian W. Kernighan and Dennis M. Ritchie's book {\em The C Programming
Language (ANSI C)}, second edition, Prentice Hall Software Series,
1988.} and the \UNIX\index{UNIX@\UNIX} operating system.\footnote{A
good description of the UNIX operating system is in the book of Brian
W. Kernighan and Rob Pike, {\em The UNIX Programming Environment},
Prentice Hall Software Series, 1984.} There is little knowledge of the
\MUSIC\ computer required to understand how to include own functions
into the NeuroBasic environment. Only functions that should be able to
run on the \MUSIC\index{music@\MUSIC} system have to be written
data-parallel (see Chapter~\ref{sec_dataparallel}). However, most of
the existing neuro-objects contain \MUSIC\ specific data and some of
the aspects of the NeuroBasic software architecture become only clear
under consideration of the \MUSIC\ computer and its development tools.




\section{Local and Parallel Version}
%===================================

Up to now we were talking of two versions of NeuroBasic, the local and
the \MUSIC\ version. In fact there is a third version, the simulator
version which is used only in the development phase. The source code
for all three versions is the same. Just the compilers and the linked
libraries differ for each version.

Any parallel code written for \MUSIC\ can be compiled and executed on
a single-processor computer as well, but, of course, not the other way
round. The three versions are described in the following.


\paragraph{Local Version} \index{local version}
The local version can be compiled for almost any workstation or
{\small PC}. It's name is {\tt nbasic}. A simple simulator interface
(in {\tt basic/simpsim.c}) makes the data-parallel code believe it
runs on a ``parallel'' environment with only one processor. All
functions from the \MUSIC\ library are shadowed and perform the right
action for the single-processor environment. Many of them, like {\tt
Wait\_data()}, just do nothing at all.

Typically, the local version of NeuroBasic runs as fast as if the code
were directly written for a single-processor machine (no loss due to
simulation of the communication).


\paragraph{MUSIC Version} \index{music version@\MUSIC\ version}
This is the high-performance version. All neuro-objects are stored and
all neuro-functions run parallel on the \MUSIC\ system. The Basic
interpreter itself runs on the host computer. To run the \MUSIC\
version just run the host part by typing {\tt mubasic}. It will
download the parallel code {\tt mubasic.lod} to the processing
elements end execute it there.

In fact, as mentioned earlier, it is not an interpreter but a compiler
that sends the compiled Basic code to all processing elements on the
\MUSIC\ system where it is executed in parallel. This is to avoid the
communication bottleneck between the host and \MUSIC.  However, since
the compilation phase is typically a fraction of a second and is
therefore not really noticeable to the user, we will refer to the host
part of NeuroBasic as the Basic interpreter.

User extensions contain only code that runs parallel on the \MUSIC\
system. All code that runs on the host is part of the Basic
interpreter.


\paragraph{Simulator Version} \index{simulator version}
For \UNIX\ systems there exists a source-level simulator, called {\tt
musim}, \index{Musim} which simulates a parallel \MUSIC\ system with
an arbitrary number of processing elements (see the Musim
tutorial). It starts a task for the host part and an additional task
for each processing element. These tasks run independently in parallel
and {\tt musim} simulates the communication between them. Any \UNIX\
debugger can be used to debug one or more of the tasks. Assembly code
can not be debugged in this way.

The host part of the simulator version is called {\tt hbasic} (for
host part) and the \MUSIC part is called {\tt sbasic} (for slave
part). To simulate NeuroBasic with {\tt musim} one has to type

\bigskip
{\tt musim }$n${ \tt sbasic hbasic}
\bigskip

\noindent where $n$ is the number of processing elements.




\section{Packages}
\index{packages|(}
%=================

The NeuroBasic development environment is divided into {\em
packages}. A package is a collection of neuro-functions and
neuro-objects which belong to a certain algorithm or a class of
algorithms. The back-propagation package, for example, contains the
objects {\em layer\/}, {\em fully connected weight sets\/}, the
functions {\tt fcprop()}, {\tt fcbackprop()} and more. It is simple to
add packages to or remove packages from NeuroBasic.

The Basic interpreter itself is just another package. It is therefore
easy to share or exchange packages among users or to update an
existing installation with the latest version of the Basic
interpreter. One also can save program space by removing unused
packages from NeuroBasic. This possibility is important if the
simulator runs on the \MUSIC\ system. The program memory of its
processing elements is restricted to 131 or 524~kByte (depending on
the hardware version) which can be too small to hold all available
NeuroBasic packages.

Each package has a subdirectory where all its files (source code,
object modules, etc.) are stored. Such a subdirectory is a small
development environment in itself. It has, for instance, its own {\tt
makefile} that compiles and links all of its code into a single object
module. In the parent directory there is a {\em global makefile\/}
\index{makefile!global} which builds the complete NeuroBasic program
by subsequently executing the local makefiles and then linking the
resulting object modules of all subdirectories together to an
executable program.

All packages that should be included are listed in a macro called {\tt
PACKAGES} defined in the file {\tt macros.mk}. This file will be
included by the global makefile. A package can therefore be added or
removed by simply editing the corresponding line at the beginning of
the global makefile. To build a NeuroBasic version with the packages
{\em backprop} and {\em example}, the corresponding place of the
global makefile would look as follows:

\begin{verbatim}
  PACKAGES = backprop example
\end{verbatim}

\noindent The {\em basic\/} package does not appear in that list
because it cannot be removed.

To regulate the interfacing mechanism between the NeuroBasic
interpreter and its packages the subdirectory of each package must
contain the following standardized files:

\begin{fctitem}{nfcts.h}
This file contains prototypes of all functions of the package that
should be ``visible'' from the Basic interpreter. The global makefile
will use this information to create a function list and interface code
for the Basic interpreter.
\end{fctitem}

\begin{fctitem}{nobjs.h}
This file contains the type definitions of all neuro-object types and
the symbolic constants \index{symbolic constants} of a package..
\end{fctitem}

\begin{fctitem}{manual.tex}
This file contains the description of the neuro-objects and
neuro-functions of the package in \LaTeX\ format. The global make file
will collect the {\tt manual.tex} files from all packages and merge
them to a complete NeuroBasic documentation. A local {\tt manual.tex}
file can be empty but it must be there.
\end{fctitem}

\begin{fctitem}{makefile}
This is the {\em local\/} makefile of the package. It must be able to
build object modules of the different program versions (\eg local or
\MUSIC\ version) and to make a backup of its complete source code.
The global makefile will link the object modules of all packages into
a final executable program.
\end{fctitem}
\index{packages|)}



\subsection{Utility Packages}
%----------------------------
Utility packages contain programs which are useful for but not a part
of NeuroBasic. They exist only as a ``local'' version (no \MUSIC\
version) and their description will go into the appendix of the
manual. A subdirectory containing a utility package must have a {\tt
makefile} and a documentation file {\tt manual.tex}.

The utility packages included into a NeuroBasic version are specified
with the macro {\tt UTILITY} in the file {\tt macros.mk} (next to
{\tt PACKAGES}).




\section{Neuro-Functions}
\index{neuro-functions|(}
%========================

Neuro-functions are normal functions written in C or assembly
language. They can be called from the NeuroBasic interpreter via a
hidden interface mechanism. Their return values are restricted to the
types {\tt MINT} {\tt MFLOAT} and {\tt void} and their parameters are
restricted to the types {\tt MINT}, {\tt MFLOAT} and {\em
strings}. \index{strings} If the function should run on the \MUSIC\
computer then, of course, it must contain data-parallel code.

\subsection{Header Files}
\index{neuro-functions!header files}
%-----------------------------------

Each C module which contains neuro-functions has to include the
following header files (from the {\tt basic} subdirectory. The
sequence of including is relevant.):

\begin{list}{}{\renewcommand{\makelabel}[1]{\tt#1}}
\item [allnfcts.h] contains the prototype of all
  neuro-functions
\item [allnobjs.h] contains the type definitions of the
  neuro-objects
\item [neurolib.h] contains various definitions which are
  used to program neuro-functions.
\end{list}



\subsection{Register Neuro-Functions}
\index{neuro-functions!registration}
%------------------------------------

To make a function ``visible'' from the NeuroBasic interpreter, the
programmer has to put an {\small ANSI}-like C prototype of the
function into the file {\tt nfcts.h} \index{nfcts.h@{\tt nfcts.h}} of
the local subdirectory of the package it belongs to. The prototype for
the squashing function ({\tt sqtanh()}) of a back-propagation layer,
for instance, is

\begin{verbatim}
  MINT sqtanh(MINT layer, MFLOAT alpha, MFLOAT beta);
\end{verbatim}

\noindent (The parameters {\em alpha\/} and {\em beta\/} are
stretching factors of the squashing function in vertical and
horizontal direction.)

Note that string parameters \index{strings} have to be declared as
arrays of characters ({\tt char~str[]}) rather than pointers to
characters ({\tt char~*str}). Otherwise the program {\tt mknfcts} will
confuse strings and open parameter lists (see
Section~\ref{sec_openpar}).

The global makefile then calls the utility program {\tt mknfcts} which
reads the {\tt nfcts.h} files of all subdirectories and creates the
two files {\tt basicif.c} and {\tt allnfcts.h} in the {\tt basic}
subdirectory. The first one contains interface code to translate the
Basic function call into a C function call and the latter one is a
list of all neuro-function prototypes of all packages. It is a good
idea to include this file into any C module which contains
neuro-function code because inconsistencies between the function
definition and its prototype are then reported by the compiler.


\subsection{Variable Number of Parameters}
\index{neuro-functions!variable parameter list}
\label{sec_openpar}
%----------------------------------------------

It is possible to write neuro-functions with a variable number of
parameters when called from the Basic interpreter. This means the
function gets as many parameters as the user types in from the Basic
interpreter. Such an open parameter list will be translated into an
array of floating-point numbers and the number of parameters and a
pointer to the array are passed to the corresponding C function. The
following example function returns the sum of its arguments.

\begin{verbatim}
  MFLOAT sum(MINT nargs, MFLOAT *pargs)
  {
    MINT i;
    MFLOAT s;

    s = 0;
    for (i = 0; i < nargs; i++) s = s + pargs[i];
    return s;
  }
\end{verbatim}

Assuming the correct declaration in {\tt nfcts.h} this function can be
called from the Basic interpreter, for example, as follows:

\begin{verbatim}
  Ok print sum(1, 4, -7, 9)
     7
\end{verbatim}

\noindent It is also possible to have a certain number of fixed
parameters in the function. Just the last two arguments must be of
type {\tt MINT} (the number of remaining arguments) and a pointer to a
floating-point array, {\tt MFLOAT*}, (the remaining arguments).

Don't use the notation {\tt MFLOAT pargs[\thinspace]} in the function
prototype because it will not be recognized by the {\tt mknfcts}
program as being a function with an open parameter list.



\subsection{Error Messages}
\index{neuro-functions!error messages}
%-------------------------------------

A neuro-function can report errors to the Basic interpreter by using
the two global variables {\tt fn\_error} and {\tt
fn\_error\_msg}. {\tt fn\_error} is an integer containing the error
code. {\tt fn\_error\_msg} is the pointer to a string containing an
error message which will be displayed on the user screen. Note that
such a string must be static, \ie it must exist also after the
neuro-function itself has terminated. The macro {\tt ERR\_GERROR}
($=~-1$) is used as error code for a general error, although the Basic
interpreter considers everything except 0 as an error code.

The Basic interpreter tests the error variable after each call of a
neuro-function. If it is nonzero, then it prints out the error message
pointed to by {\tt fn\_error\_msg} and stops the execution of the
Basic program.

The following error codes have predefined error messages. If they are
used, no message needs to be written into {\tt fn\_error\_msg}.

\bigskip
\begin{tabular}{lrl}
{\tt ERR\_NOERROR}        & $ 0$    & (no error)\\
{\tt ERR\_OBJTABFULL}     & $-2$    & (object table full)\\
{\tt ERR\_NOMEM}          & $-3$    & (not enough memory)\\
{\tt ERR\_NOOBJ}          & $-4$    & (not an object)\\
{\tt ERR\_WRONGOBJ}       & $-5$    & (wrong object type)\\
{\tt ERR\_PARCONF}        & $-6$    & (parameter conflict)\\
{\tt ERR\_DISKERROR}      & $-7$    & (disk I/O error)\\
{\tt ERR\_NOFILE}         & $-8$    & (file not found)\\
\end{tabular}
\index{neuro-functions|)}




\section{Neuro-Objects}
\index{neuro-objects|(}