basic.tex

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

% *******************************************************************
%
% File:         basic.tex
%
% Project:      NeuroBasic, basic backage
%
% Survey:       Documents the concept of NeuroBasic and describes
%               the usage of the Basic interpreter.
%
% Author:       Urs Mueller
%               Electronics Laboratory, ETH Zuerich,
%               Switzerland
%
% Created:      July 24, 1994
% Modified:     July 31, 1995 (um)
%
% *******************************************************************




\chapter{Introduction}
%*********************

{\em NeuroBasic\/} is a flexible and interactive simulation
environment for neural networks which runs on a parallel
supercomputer. The Basic programming language (Beginner's All-purpose
Symbolic Instruction Code) is used to control experiments by executing
powerful neuro-functions. These neuro-functions create neuro-objects
(layers, weight sets, etc.), combine such objects into a complete
neural network and train such networks with arbitrary patterns of one
or more pattern sets. The Basic interpreter allows all kinds of
gradations in experimental research, from small interactive on-line
experiments till complete experimental series which run off-line in
the background.

NeuroBasic runs either on a workstation or {\small PC} or on the
\MUSIC\index{music@\MUSIC} parallel computer. The \MUSIC\ system is a
parallel supercomputer (distributed memory, {\small MIMD}) with up to
63 processing elements and a peak performance up to 3.8~Gflops. It
works as an attached processor on a host computer. The Basic
interpreter runs as an interactive program on the host computer,
whereas the neuro-functions are executed very fast on the parallel
\MUSIC\ system. It typically speeds up the experiments by a factor of
30 to 300 compared to modern workstations and often outperforms even
conventional supercomputers.
The reasons for choosing Basic as the command language are the
followings:

\begin{itemize}
\item Basic is interactive what avoids a compilation phase. This
  dramatically reduces turnaround times. Furthermore, it allows the
  on-line experimenting as well as running large batch jobs, all in
  the same environment.
\item The high flexibility of the language allows to take maximum
  advantage of the freedom provided by the neuro-functions.
\item Basic is very easy to learn and to use (it was developed at
  Dartmouth College for students who were unfamiliar with computers).
\item Basic is widely spread. Many people therefor don't have to learn
  a new language in order to use neural networks and to take advantage
  of the \MUSIC\ parallel supercomputer.
\end{itemize}





\chapter{Installation}
\index{installation}
%*********************

The NeuroBasic simulation environment is installed by simply copying
the necessary files to the desired location. It exists in two
versions.

\begin{enumerate}
\item \index{local version} The {\em local version\/} contains only an
  executable program and example Basic programs. It is available for
  almost any Workstation and \PC. The complete simulation environment
  is just one program, named {\tt nbasic} or {\tt nbasic.exe} which is
  ready to run.
\item \index{developer version} The {\em developer version\/} contains
  the complete source code for the simulation environment which is
  organized in a directory tree. There is a \UNIX\ makefile to create
  a local or a parallel \MUSIC\ version of the simulator (both have
  the same source code). The Chapter {\em User Extensions} of the
  developer version's manual describes how to extend the simulator
  with own algorithms. To be able to compile a \MUSIC\ version the
  \MUSIC\ development system must be installed (see \MUSIC\ Tutorial).
\end{enumerate}

\noindent For both versions the {\tt readme.txt} file contains
information about the latest updates.




\section{Starting NeuroBasic}
\index{starting NeuroBasic}
%============================

NeuroBasic is started by simply typing its name, which is {\tt nbasic}
for the local version and {\tt mubasic} for the parallel \MUSIC\
version. It then prints out the version number and compilation date
and then announces its readyness by printing the prompt {\tt Ok}. A
simple session could look as follows:

\begin{verbatim}
     Welcome to Neuro-Basic V3.0. Last compilation: Jul 27 1995
  Ok print "Hello!"
     Hello!
  Ok a = 7  
  Ok print (a + 4) * 2
     22
  Ok 10 for i = 1 to 5
  Ok 20 print i; "*" i; "="; i*i 
  Ok 30 next i
  Ok 40 end
  Ok run
     1*1=1
     2*2=4
     3*3=9
     4*4=16
     5*5=25
  Ok quit
\end{verbatim}

\noindent It is possible to start NeuroBasic with names of Basic files
as arguments which should be executed. NeuroBasic loads and executes
these files and terminates afterwards. For example,

\begin{verbatim}
  nbasic demo.bas
\end{verbatim}

\noindent will execute the file {\tt demo.bas}.




\section{Starting the MUSIC Version on UNIX Systems}
\index{MUSIC version@\MUSIC\ version} \index{UNIX@\UNIX}
%===============================================================

On \UNIX\ computers the \MUSIC\ system does not necessarily have to be
attached to the local machine. Any \MUSIC\ system who's host computer
is accessible over the network can be used. One host computer can also
control more than one \MUSIC\ system. A \MUSIC\ system therefore is
specified by the name of its host and a link number. The program {\tt
muquery} (see \MUSIC\ Tutorial) prints out a list of the available
\MUSIC\ systems in the local net.

By default NeuroBasic chooses the smallest free \MUSIC\ system on the
local net. The {\tt -s} option allows to specify a particular system
by giving a host name and a link number. For example

\begin{verbatim}
  mubasic -s rexy 0
\end{verbatim}

\noindent will choose the \MUSIC\ system on link 0 of the machine {\tt
rexy}. Note that the Basic interpreter will still run on the local
machine. {\tt rexy} is just the server.

Yet another way to select \MUSIC\ systems is to create a file named
{\tt link.cnf} with a list of \MUSIC\ systems in the local directory.
When started, NeuroBasic will select the first free system of the
list. The list must contain the host name and link number on a
separate line of text for each system.

In fact, if there is no file named {\tt link.cnf}, then NeuroBasic
will create it first, afterwards boot the \MUSIC\ system and then
remove it again. If, for any reason, NeuroBasic is aborted during
booting the \MUSIC\ system, then the created file {\tt link.cnf} will
not be removed.




\chapter{The Basic Language}
\index{Basic language|(}
%***************************

Basic knows two classes of commands: global commands (like {\tt load},
{\tt save}, {\tt list}) and program statements and expressions (like
{\tt goto}, {\tt print}, {\tt a~=~5}). Commands of the first class
can only be typed interactively, while commands of the second class
can either be used interactively or can be built into a Basic program.


\section{Global Commands}
%========================

\begin{nbcommand}{run} 
  Runs the present Basic program. No parameters. A running Basic
  program can be terminated by sending an interrupt signal from the
  keyboard. This is, for instance, Ctrl-C on a Unix host or Ctrl-D on
  an {\small Atari} host. The Basic program will be terminated after
  the next screen output from a {\tt print} command. Two consecutive
  interrupt signals will kill NeuroBasic itself. If no Basic program
  is running, a single interrupt signal will kill NeuroBasic.

  {\tt run} previously clears all Basic variables and releases all
  neuro-objects. To continue with an experiment type {\tt goto}
  followed by a line number. This will resume program execution at the
  indicated program line.
\end{nbcommand}
 
\begin{nbcommand}{list} 
  List the present Basic program on the screen. A line-number to start
  the listing can be specified. If no parameter is given, the command
  continues listing the program code where it had stopped before. An
  attempt to list past the end of the program causes the following
  message: ``Exceeded end of program.''
\end{nbcommand}

\begin{nbcommand}{new} 
  Deletes the present Basic program from the memory. A single line can
  be deleted by simply typing the line number directly followed by
  {\tt [Return]}. Note that {\tt new} does not clear any
  variables. This will be done when executing a new program with {\tt
  run} or by using the clear command (see below).
\end{nbcommand}

\begin{nbcommand}{clear} 
  Clears all Basic variables and releases all neuro-objects.
\end{nbcommand}

\begin{nbcommand}{load} 
  Loads a Basic program from disk into the memory. A filename must be
  specified. The file format is plain \ASCII. Larger Basic programs
  can therefore be created off-line by using any preferred editor. The
  Basic file can be written with or without line numbers. If no line
  numbers are used they will be created automaticaly when loading the
  file.
\end{nbcommand}

\begin{nbcommand}{save} 
  Saves the present Basic program {\em without} line numbers
  to disk. A filename must be specified. Note: When reloading the
  saved file, the Basic file is renumbered automatically in equal
  steps. The new line numbers can differ form the original
  version. Therfore when using commands like {\tt goto, gosub, then,
  ... } jump references by labels rather than by line numbers are
  recommended.
\end{nbcommand}

\begin{nbcommand}{saven} 
  Saves the present Basic program {\em with} line numbers
  to disk. A filename must be specified.
\end{nbcommand}

\begin{nbcommand}{version} 
  Prints the current version and the compilation date of
  the neuro-simulator (not the Basic interpreter) or another
  application the Basic interpreter is used for.
\end{nbcommand}

\index{"!@{\tt "!}}
\begin{nbcommand}{!}  
  Executes a shell command. The format of the command string
  is system dependent. On Unix computers the standard Unix shell {\tt
  sh} (Bourne Shell) is invoked to execute the command.
\end{nbcommand}

\begin{nbcommand}{quit} 
  To quit the program. {\tt exit} and {\tt q} are recognized as well.
\end{nbcommand}




\section{Program Statements}
%===========================

\begin{nbcommand}{end} 
  To mark the end of a Basic program. Returns control to the
  interpreter.
\end{nbcommand}

\begin{nbcommand}{rem} 
  (Remember) Ignores the rest of the line. It is used to add
  comments to the program code.
\end{nbcommand}

\index{"!@{\tt "!}} 
\begin{nbcommand}{!} 
  Equivalent to {\tt rem}.
\end{nbcommand}

\begin{nbcommand}{return} 
  Return from subroutines (called by {\tt gosub}).
\end{nbcommand}

\begin{nbcommand}{input} 
  Stops the program flow and waits for the user input of a
  number which afterwards is assigned to the specified variable.
\end{nbcommand}

\begin{nbcommand}{if} 
  Conditional program execution.\\ Syntax: {\tt if
  <expression> then <command>}\\ Example:
\begin{verbatim}
    if a > 7 then print "a is greater than 7"
\end{verbatim}
  Instead of a command there can directly be a program line number or
  a label, \ie
\begin{verbatim}
    if a > 7 then goto 50
\end{verbatim}
  and
\begin{verbatim}
    if a > 7 then 50
\end{verbatim}
  are equivalent.
\end{nbcommand}

\begin{nbcommand}{:} 
  The colon seperates two commands or statements placed on the
  same program line. After an {\tt if/then} condition all commands on
  the same line are conditionally executed. For example,
\begin{verbatim}
    if 3 > a then print 3 : print a
\end{verbatim}
  prints 3 and {\tt a} only if 3 is greater than {\tt a}.
\end{nbcommand}

\begin{nbcommand}{print} 
  To print constants, variables, constant strings or string
  variables on the screen. Items to print have to be separated by a
  semicolumn (;) which prints the items without white space in between
  or by a column (,) which separates the items by a tab. A column or
  semicolumn at the end of the item list prevents the printing of a
  carriage return.
\end{nbcommand}

\begin{nbcommand}{?} 
Equivalent to {\tt print}.
\end{nbcommand}

\begin{nbcommand}{fprint} 
  {\tt fprint "filename", ...} produces exactly the same
  output as {\tt print ...} but writes it to the file {\tt
  filename}. The filename can be a string, a string variable or a
  string expression and is separated from the print statement by a
  column (,).
\end{nbcommand}

\begin{nbcommand}{label} 
  {\tt label <labelname>} specifies a line in the Basic
  program to where can be jumped with commands like {\tt goto}, {\tt
  gosub}, etc. It is recommended to use labels rather than line
  numbers to make the Basic program line-number invariant (see {\tt
  save, saven}).
\end{nbcommand}
 
\begin{nbcommand}{goto} Jump to the specified program line or label.
\end{nbcommand}

\begin{nbcommand}{gosub} 
  Jump to the subroutine starting at the specified program
  line or label. The subroutine must end with a {\tt return}
  instruction.
\end{nbcommand}

\begin{nbcommand}{for} 
  Loop constructor. The syntax is:\\ {\tt for <variable> =
  <expression> to <expression>}
\end{nbcommand}

\begin{nbcommand}{next} 
  Close the loop opened by {\tt for}. Increment the
  specified variable (loop counter) by one and compare it with the
  second expression of the corresponding {\tt for} command. Nested
  {\tt for/next} loops are allowed. Syntax: {\tt next <variable>}
\end{nbcommand}


\paragraph{Warning:}
The program syntax is not fully verified. Syntax errors may cause
crashes in seldom cases.



\section{Expressions}
\index{expressions}
%====================

Expressions are evaluated recursively. They can contain constant
numbers, variables, arrays, function calls and the operaters listed in
Table ~\ref{tab_operators}. Operators of the same level are evaluated
from the left to the right. Parentheses can be nested. The {\tt mod}
and {\tt div} operators consider only the integer parts of thir
operands.

\begin{table}[htb]
\hfil
\begin{tabular}{|ll|}
  \hline
  {\tt - not ()}        & change sign, logical negation, parentheses \\
  {\tt $\wedge$}
    {\em or} {\tt **}   & power of\\