basic.tex

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

  {\tt * / div mod} 
    {\em or} {\tt \%}   & multiply, divide, integer divide, modulo \\
  {\tt + -}             & add, subtract\\
  {\tt = < > <= >= <>}
    {\em or} {\tt \#}   & relational operators \\
  {\tt and}             & logical {\small AND} \\
  {\tt or exor}         & logical {\small OR} and exclusive
                          {\small OR}\\
  \hline
\end{tabular}
\caption{Basic operators, listed in the order of precedence.}
\label{tab_operators}
\end{table}

Logical operators interprete the number 0 as the logical state {\small
FALSE} and nonzero number as {\small TRUE}. Likewise is the result of
logical operations 0 for {\small FALSE} and 1 for {\small TRUE}.



\section{Variables}
\index{variables}
%==================
All {\em variables\/} are floating-point (32 bit). Variable names are
case sensitive and can contain all regular letters ({\tt a\ldots z,
A\ldots Z}) and the underscore ({\tt\_}) character. Digits ({\tt
0\ldots9}) are allowed as part of a variable name, except for the
first character which must be a nondigit. The predefined keywords
listed in Table~\ref{tab_keywords} cannot be used as variable names
(neither in lower case, uper case or mixed).

\begin{table}[htb]
\hfil{\tt
\begin{tabular}{|llllll|}
  \hline
  and           &
  deffn         &
  dim           &
  div           &
  end           &
  endfn         \\
  exor          &
  for           &
  fprint        &
  gosub         &
  goto          &
  if            \\
  input         &
  label         &
  let           &
  mod           &
  next          &
  not           \\
  or            &
  print         &
  rem           &
  return        &
  then          &
  to            \\
  \hline
\end{tabular}}
\caption{Predefined keywords which cannot be used as variable names.}
\label{tab_keywords}
\end{table}

To assign values to a variable the {\tt =}-operator is used,
for example
\begin{verbatim}
   a = 5
\end{verbatim}
or
\begin{verbatim}
   a = a + 1
\end{verbatim}
Variable are created automatically the first time a value is assigned
to them. There is no varaible declaration part in a Basic program.



\section{Arrays}
\index{arrays}
%===============
Arrays are one-dimensional vectors of floating-point numbers.
The rules for variable names also are true for array names. In
contrast to variables, arrays have to be declared before they can be
used. This is necessary to tell Basic the size of the array and is
accomplished with the {\tt dim} statement. The following
example declares an array {\tt a} of size 10:
\begin{verbatim}
   dim a[10]
\end{verbatim}
The size of the array (10 in the above case) does not have to be a
constant number, it can be an expression:
\begin{verbatim}
   size = 10
   dim a[size+5]
\end{verbatim}
Multiple arrays can be declared with one {\tt dim} statement:
\begin{verbatim}
   dim a[10], b[100], cc[3]
\end{verbatim}
The smallest array index always is zero, so the array {\tt a} has
elements in the range 0\ldots9. The array elments can be
referenced by putting the index in square brackets. The indices may be
expressions themselves, for example:
\begin{verbatim}
    dim a[10]
    i = 2
    a[i+2] = i * i
    print a[4]
\end{verbatim}
Arrays and variables can use the same names. Basic distinguishes them
by the square bracket ({\tt[}) which always follows an array name.

If a second declaration occurres for an already existing array, then
it's size will be changed to the new size. The content of the array
will be unchanged up to the minimum of the old and new sizes.  New
arrays or parts thereof, created with {\tt dim}, will be initialized
with zeros.



\section{Strings}
\index{strings}\index{string variables}\index{string constants}
%==============================================================
Strings are a piece of text and string variables contain
strings. Their names, again, have the same rules as variable
names. They are distinguished from regular variables by a trailing
{\tt\$} character. String constants (a string which is rpresented
directly by its text), have to be in quotes. Example:
\begin{verbatim}
   filename$ = "data.mat"
\end{verbatim}
Strings are allowed in the following simple expressions:
\begin{itemize}
\item Assignment of a constant string or a string variable
  to a string variable: {\tt  = }
\\Example: {\tt a\$ =  "digits"}
\item Concatenation of two or more strings or string
  variables: {\tt  + } 
\\Example: {\tt b\$ = a\$ +  "10" + ".mat"}
\item Conversion of the value of a variable into a string: 
   {\tt str\$()}
\\Example: {\tt a\$ =  "digits" + str\$(5)}
\end{itemize}
The example program shows how to generate the five file names
{\tt digits0.mat, $\dots$, digits4.mat} during run time and to load
the correspondent pattern files.
\begin{verbatim}
    dim patt[5]
    a$ = "digits"
    b$ = ".mat"
    for i = 0 to 4
    patt[i] = new_patterns(10, 100, 1)
    load(patt[i], a$ + str$(i) + b$)
    next i
\end{verbatim}

  


\section{Function Calls}
\index{function calls}
%=======================
The parameters of a function are enclosed by parentheses {\tt ()} and
separated by commas. Parameters can be single values or
expressions. The following example
\begin{verbatim}
  max(3,2+3)
\end{verbatim}
will return 5 (the maximum of the two numbers 3 and 5). The
parentheses are required even if the function has no parameters, for
example,
\begin{verbatim}
  t = clock()
\end{verbatim}
NeuroBasic knows three types of functions. They are all called with
the same syntax.
\begin{enumerate}
\item \index{built-in functions} {\em Built-in functions\/} are a
  fixed part of NeuroBasic. They are mainly mathematical functions,
  like $\sin(x)$, $\exp(x)$, etc. (see Section~\ref{sec_builtin}).

\item \index{neuro-functions} {\em Neuro-functions\/} are written in C
  or assembly language and made executable from the Basic
  interpreter. The developer version of NeuroBasic allows the user to
  write own neuro-functions.

\item \index{Basic functions}\index{user-defined functions} {\em
  User-defined Basic functions\/} are written in Basic code itself
  (see Section~\ref{sec_bfunctions}. They consist of a name, a
  parameter list, several program lines, and a return parameter. They
  can be used to create more powerful functions from neuro- and
  built-in functions.
\end{enumerate}




\section{Built-In Functions}
\label{sec_builtin}
\index{built-in functions}
%===========================

The following is a list of built-in functions. Their names are case
insensitive ({\tt sin(2.1)}, {\tt SIN(2.1)} and {\tt Sin(2.1)} are
equivalent. All other function names (neuro-functions and user-defined
Basic functions) are case sensitive!

\begin{list}{}{
\setlength{\labelwidth}{5em}
\setlength{\leftmargin}{6em}
\setlength{\labelsep}{1em}      % \leftmargin - \labelwidth
\setlength{\rightmargin}{0em}
\setlength{\parsep}{0ex}
\setlength{\itemsep}{0.1ex}
\renewcommand{\makelabel}[1]{\tt#1\hfil}
}
\item[abs(x)] \index{abs@{\tt abs()}} Returns the absolute value, or
  magnitude, of {\tt x}.

\item[ip(x)] \index{ip@{\tt ip()}} Returns the integer part of {\tt
  x}.

\item[int(x), floor(x)] \index{int@{\tt int()}}
  \index{floor@{\tt floor()}} Return the greatest integer less than or
  equal to {\tt x}; 
  differs from {\tt ip()} with negative numbers.

\item[fp(x)] \index{fp@{\tt fp()}}
Returns the fractional part of {\tt x}.

\item[ceil(x)] \index{ceil@{\tt ceil()}}
Returns the smallest integer greater than or equal to {\tt x}.

\bigskip

\item[sqrt(x)] \index{sqrt@{\tt sqrt()}}
Returns the positive square root of nonnegative {\tt x}.

\item[sgn(x)] \index{sgn@{\tt sgn()}} Sign function, returning 1 if
  {\tt x} is positive, 0 if {\tt x} is zero, and $-1$ if {\tt x} is
  negative.

\item[max(x,y)] \index{max@{\tt max()}} Compares {\tt x} and {\tt y},
  returning the larger of the two values.

\item[min(x,y)] \index{min@{\tt min()}} Compares {\tt x} and {\tt y},
  returning the smaller of the two values.

\bigskip

\item[log(x)] \index{log@{\tt log()}} Returns the natural (base $e$)
  logarithm of a positive {\tt x}.

\item[exp(x)] \index{exp@{\tt exp()}} Returns $e^x$ (antilogarithm) of
  {\tt x}.

\item[lgt(x)] \index{lgt@{\tt lgt()}} Returns the common (base 10)
  logarithm of a positive {\tt x}.

\bigskip

\item[sin(x)] \index{sin@{\tt sin()}} Sine of {\tt x}.

\item[asn(x)] \index{asn@{\tt asn()}} Arcsine of {\tt x}; $-1\leq
  x\leq1$. In first or fourth quadrant.

\item[cos(x)] \index{cos@{\tt cos()}} Cosine of {\tt x}.

\item[acs(x)] \index{acs@{\tt acs()}} Arccosine of {\tt x}; $-1\leq
  x\leq1$. In first or fourth quadrant.

\item[tan(x)] \index{tan@{\tt tan()}} Tangent of {\tt x}.

\item[atn(x)] \index{atn@{\tt atn()}} Arctangent of {\tt x}; in first
  or fourth quadrant.

\item[atn2(y,x)] \index{atn2@{\tt atn2()}} Arctangent of {\tt y/x} in
  proper quadrant. ({\tt x,y}) is the rectangular coordinate position
  of a point.

\item[sinh(x)] \index{sinh@{\tt sinh()}} Hyperbolic sine of {\tt x}.

\item[cosh(x)] \index{cosh@{\tt cosh()}} Hyperbolic cosine of {\tt x}.

\item[tanh(x)] \index{tanh@{\tt tanh()}} Hyperbolic tangent of {\tt
  x}.

\item[str\$(x)] \index{str@{\tt str\$()}} Conversion of {\tt x} into a
  string.

\item[exist(var)] \index{exist@{\tt exist()}} This function returns 1
  (the boolean value for {\tt TRUE}) if the variable named {\tt var}
  exists, \ie if a variable previously has been assigned to it.
  Otherwise the function returns 0 ({\tt FALSE}). It is mostly used in
  conditional statements ({\tt if exist(a) then ...}).
 
\bigskip

\item[clock()] \index{clock@{\tt clock()}} The function {\tt clock()}
  returns the {\small CPU} time \index{CPU@{\small{}CPU}~time}in
  seconds passed since the beginning of execution of NeuroBasic. On
  the \MUSIC\ system this is equal to the actual time, whereas
  workstations usually only count the {\small CPU} time used by
  NeuroBasic (not counting {\small CPU} time used by other
  programs). The time wraps around (starts at zero again) after
  approximately 1.2 hours.

  For performance measurements the measured interval should be larger
  than one second. The resolution of the {\tt clock()} function on a
  Sun is 16.667\thinspace{}ms. On a \MUSIC\ system there is an
  inaccuracy of up to 0.1 seconds!

\bigskip

\item[system("shell command")] \index{system@{\tt system()}} Executes
  a shell command like the global command ``!''. The difference is
  that this function can be built into basic programs. The format of
  the shell command is system dependent. On Unix computers the
  standard Unix shell {\tt sh} (Bourne Shell) is invoked to execute
  the command.

  Return value is the exit value of the shell.

\end{list}




\section{User-Defined Basic Functions}
\label{sec_bfunctions}
\index{Basic functions}\index{user-defined Basic functions}
%==========================================================
A basic function is a function defined by the user within a Basic
program. It can be called just like a built-in or a
neuro-function. The block of statements defining a function must begin
with a {\tt deffn} and end with a {\tt endfn} statement:
\begin{verbatim}
     deffn <function name>(<arg1>, <arg2>, ...)
     ...
     endfn
\end{verbatim}
A return value is assigned with a ``{\tt =}''-statement to the
function name. Example:
\begin{verbatim}
     10 print sq(3)
     20 end
     30 deffn sq(x)
     40 sq = x * x
     50 endfn
\end{verbatim}
Basic variables can be used within a function definition (all
variables are global) but note that parameters in the function
declaration (like {\tt x} in the above example) and the function name
itself shadow global variables with the same name. This means that if
a global variable with name {\tt x} exists it cannot be accessed
within the function {\tt sq()}. Note: String variables cannot be used
as arguments.

A function can call itself (recursion) but a function definition
within a function definition is not allowed. The following example
illustrates the recursive computation of factorials.
\begin{verbatim}
   10 end
   20 deffn factorial(n)
   30 factorial = 1
   40 if n > 0 then factorial = n * factorial(n-1)
   50 endfn

   Ok print factorial(5)
      120
   Ok
\end{verbatim}



\section{b-Code}
\index{b-code}
%===============

The Basic language is interactive and usually interpreted at runtime.
However, interpreting commands on a sequential (host) computer and
executing them on a very fast parallel system is problematic. This is
because the time needed to interpret the commands and send them to
the parallel system easily exceeds the time needed to execute the
commands. This means the overall performance is dominated by the host
computer and the communication between the host and the parallel
system and there is a hard limit in performance (Amdahl's law) which
cannot be exceeded, no matter how fast the parallel system is.

Therefore the host computer does not interpret the Basic code
but compiles it into a low-level language called {\em b-code}. The
b-code is copied to all processing elements of the parallel system
and is executed there in parallel. This means each processor ``knows''
what to do for the duration of the complete Basic program and no
communication to the host is necessary.

The compilation phase is not really noticeable to the user because it
is invoked automatically. Compiling 1000 lines of Basic code takes
less than a second on a Sun Sparcstation~2. The Simulation environment
therefore still feels as being interactive.  \index{Basic language|)}