\chapter{Running SNNS as Batch Job}
\label{SNNSBatch}
\thispagestyle{empty}

\index{Batch Job}
Since training a neural network may require several hours of
CPU time, it is advisable to perform this task as a batch job during
low usage times. SNNS offers the program {\tt snnsbat} for this
purpose. It is basically an additional interface to the kernel that
allows easy background execution. Its flexible setup allows for a
variety of possible execution modes which can be easily defined in a
configuration file. All actions and messages are recorded in a log
file for later verification of results.

\section{The Snnsbat Environment}

\index{snnsbat}
{\tt snnsbat} runs very dependably even on unstable system
configurations and is secured against data loss due to system crashes,
network failures etc.. On UNIX based systems the program may be
terminated with the command 'kill -15' without loosing the currently
computed network.

The calling syntax of snnsbat is:

\centerline{snnsbat $[<$ configuration\_file $>[<$ log\_file $>]$ $]$}

This call starts {\tt snnsbat} in the foreground. On UNIX systems the
command for background execution is `at', so that the command line\\
\centerline{echo 'snnsbat default.cfg log.file' $\mid$ at 22:00} would
start the program tonight at 10pm\footnote{This construction is
necessary since `at' can read only from stdin.}.

If the optional file names are omitted, {\tt snnsbat} tries to open
the configuration file `./snnsbat.cfg' and the protocol file
`./snnsbat.log'. 

\section{Using Snnsbat}

\index{snnsbat!Configuration File}
The batch mode execution of SNNS is controlled by the configuration
file. It contains entries that define the network and parameters
required for program execution. These entries are tuples (mostly
pairs) of a keyword followed by one or more values.  There is only one
tuple allowed per line, but lines may be separated by an arbitrary
number of comment lines. Comments start with the number sign '\#'.
The set of given tuples specify the actions performed by SNNS in one
execution run. An arbitrary number of execution runs can be defined in
one configuration file, by separating the tuple sets with the keyword
'PerformActions:'. Within a tuple set, the tuples may be listed in any
order. If a tuple is listed several times, values that are already
read are overwritten. The only exception is the key 'Type:', which has
to be listed only once and as the first key.  If a key is omitted, the
corresponding value(s) are assigned a default.

%\clearpage

Here is a listing of the tuples and their meaning:
%\vspace{0.5cm}

\begin{tabular}{|llp{68mm}|}
\hline
Key             &Value          &Meaning\\ \hline \hline

InitFunction:   &$<$string$>$           &Name of the initialization
function.\\

InitParam:      &$<$float$>$ $\cdots$ &'NoOfInitParam' pa\-ra\-meters
for in\-i\-tiali\-zation function, separated by blanks.\\

LearnParam:     &$<$float$>$ $\cdots$ &'NoOfLearnParam' parameters
for learning function, separated by blanks.\\

UpdateParam:    &$<$float$>$ $\cdots$ &'NoOfUpdateParam' parameters
for the update function, separated by blanks.\\

LearnPatternFile: &$<$string$>$         &Filename of the learning patterns.\\

MaxErrorToStop: &$<$float$>$        &Network error when learning is to
be halted.\\

MaxLearnCycles: &$<$int$>$              &Maximum number of learning
cycles to be executed.\\

NetworkFile:    &$<$string$>$    &Filename of the net to be trained.\\

NoOfInitParam:  &$<$int$>$ &Number of parameters for the initialization
function.\\ 

NoOfLearnParam: &$<$int$>$ &No of parameters for learning function.\\

NoOfUpdateParam: &$<$int$>$ &No of parameters for update function.\\

NoOfVarDim:     &$<$int$>$ $<$int$>$   &Number of variable dimensions of
the input and output patterns.\\

PerformActions:         &none &Execution run separator.\\

PruningMaxRetrainCycles: & $<$int$>$ & maximum no. of cycles per
retraining \\

PruningMaxErrorIncrease: & $<$float$>$ & Percentage to be added to the
first net error. The resulting value cannot be exceeded by the net
error, unless it is lower than the accepted error \\

PruningAcceptedError: & $<$float$>$ & Maximum accepted error.\\

PruningRecreate: & [ YES $|$ NO ] & Flag for reestablishing the last
state of the net at the end of pruning \\

PruningOBSInitParam: & $<$float$>$ & initial value for OBS \\

PruningInputPruning: & [ YES $|$ NO ] & Flag for input unit pruning \\

PruningHiddenPruning: & [ YES $|$ NO ] & Flag for hidden unit pruning \\

ResultFile:     &$<$string$>$           &Filename of the result
file.\\
\hline
\end{tabular}

\clearpage

\begin{tabular}{|llp{70mm}|}
\hline
Key             &Value          &Meaning\\ \hline \hline

ResultIncludeInput:     &[ YES $|$ NO ]         &Flag for inclusion of input
patterns in the result file.\\

ResultIncludeOutput:    &[ YES $|$ NO ]         &Flag for inclusion of output
learning patterns in the result file.\\ 

SubPatternOSize: &$<$int$>$ $\cdots$ &NoOfVarDim[2] int values that specify
the shape of the sub patterns of each output pattern.\\

SubPatternOStep: &$<$int$>$ $\cdots$ &NoOfVarDim[2] int values that
specify the shifting steps for the sub patterns of each output pattern.\\

TestPatternFile: &$<$string$>$          &Filename of the test patterns.\\

TrainedNetworkFile:   &$<$string$>$     & Filename where the net should
be stored after training / initialization.\\

Type:           &$<$string$>$   &The type of grammar that corresponds
to this file. Valid types are:\\ & &'SNNSBATCH\_1': performs only one
execution run.\\ & &'SNNSBATCH\_2': performs multiple execution runs.\\ 

ResultMinMaxPattern:    &$<$int$>$ $<$int$>$ &Number of the first and
last pattern to be used for result file generation.\\

Shuffle:        &[ YES $|$ NO ]         &Flag for pattern shuffling.\\

ShuffleSubPat:  &[ YES $|$ NO ]         &Flag for subpattern shuffling.\\

SubPatternISize: &$<$int$>$ $\cdots$ &NoOfVarDim[1] int values that specify
the shape of the sub patterns of each input pattern.\\

SubPatternIStep: &$<$int$>$ $\cdots$ &NoOfVarDim[1] int values that
specify the shifting steps for the sub patterns of each input pattern.\\
\hline
\end{tabular}

%\vspace{0.5cm}
Please note the mandatory colon after each key and the upper case of
several letters.

{\tt snnsbat} may also be used to perform only parts of a regular
network training run. If the network is not to be initialized,
training is not to be performed, or no result file is to be computed,
the corresponding entries in the configuration file can be omitted.

For all keywords the string '$<$OLD$>$' is also a valid value. If
$<$OLD$>$ is specified, the value of the previous execution run is
kept. For the keys 'NetworkFile:' and 'LearnPatternFile:' this means,
that the corresponding files are not read in again. The network
(patterns) already in memory are used instead, thereby saving
considerable execution time. This allows for a continuous logging of
network performance. The user may, for example, load a network and
pattern file, train the network for 100 cycles, create a result file,
train another 100 cycles, create a second result file, and so forth.
Since the error made by the current network in classifying the
patterns is reported in the result file, the series of result files
document the improvement of the network performance.

\clearpage

The following table shows the behavior of the program caused by omitted
entries:

\vspace{0.5cm}

\begin{tabular}{|l|p{90mm}|}
\hline

missing key             &resulting behavior\\ \hline \hline

InitFunction:           &The net is not initialized.\\

InitParam:              &Init function gets only zero values as parameters.\\ 

LearnParam:             &Learning function gets only zero values as
                        parameters.\\ 

UpdateParam:            &Update function gets only zero values as
                        parameters.\\ 

LearnPatternFile:       &Abort with error message if more than 0
                        learning cycles are specified. Initialization
                        can be performed if init function does not
                        require patterns.\\

MaxErrorToStop:         &Training runs for 'MaxLearnCycles:' cycles.\\

MaxLearnCycles:         &No training takes place. If training is
supposed to run until {\sl MaxErrorToStop}, a rather huge number
should be supplied here. (skipping this entry would inhibit training
completely).\\  

NetworkFile:            &Abort with error message.\\

NoOfInitParam:          &No parameters are assigned to the
                        initialization function. 
                        Error message from the SNNS kernel possible.\\
%\hline
%\end{tabular}

%\clearpage

%\begin{tabular}{|l|p{105mm}|}
%\hline

%missing key            &resulting behavior\\ \hline \hline

NoOfLearnParam:         &No parameters are assigned to the learning function.
                        Error message from the SNNS kernel possible.\\

NoOfUpdateParam:        &No parameters are assigned to the update function.\\

NoOfVarDim:             &Network can not handle variable pattern sizes.\\
PerformActions:         &Only one execution run is performed. Repeated
keywords lead to deletion of older values.\\

ResultFile:             &No result file is generated.\\

ResultIncludeInput:     &The result file does NOT contain input Patterns.\\

ResultIncludeOutput:    &The result file DOES contain learn output
Patterns.\\

ResultMinMaxPattern:    &All patterns are propagated.\\

Shuffle:                &Patterns are not shuffled.\\

ShuffleSubPat:          &Subpatterns are not shuffled.\\

SubPatternISize:        & \\
SubPatternIStep:        & \\
SubPatternOSize:        & \\
SubPatternOStep:        &Abort with error message if `NoOfVarDim:' was
specified.\\

TestPatternFile:        &Result file generation uses the learning patterns.
                        If they are not specified either, the program
                        is aborted with an error message when trying
                        to generate a result  file.\\

TrainedNetworkFile:     &Network is not saved after training /
                        initialization. It is used for
                        result file generation.\\ 

Type:                   &Abort with error message.\\
\hline
\end{tabular}

\vspace{1cm}
\clearpage
Here is a typical example of a configuration file:

{\footnotesize
\begin{verbatim}

    #
    Type: SNNSBATCH_2
    #
    # If a key is given twice, the second appearance is taken.
    # Keys that are not required for a special run may be omitted.
    # If a key is omitted but required, a default value is assumed.
    # The lines may be separated with comments.
    #
    # Please note the mandatory file type specification at the beginning and 
    # the colon following the key.
    #
    #######################################################################
    NetworkFile: /home/SNNSv4.0/examples/letters.net
    #
    InitFunction: Randomize_Weights
    NoOfInitParam: 2
    InitParam: -1.0 1.0
    #
    LearnPatternFile: /home/SNNSv4.0/examples/letters.pat
    NoOfVarDim: 2 1
    SubPatternISize: 5 5
    SubPatternOSize: 26
    SubPatternIStep: 5 1
    SubPatternOStep: 1
    NoOfLearnParam: 2
    LearnParam: 0.8 0.3
    MaxLearnCycles: 100
    MaxErrorToStop: 1
    Shuffle: YES
    #
    TrainedNetworkFile: trained_letters.net
    ResultFile: letters1.res
    ResultMinMaxPattern: 1 26
    ResultIncludeInput: NO
    ResultIncludeOutput: YES
    #
    #This execution run loads a network and pattern file with variable
    #pattern format, initializes the network, trains it for 100 cycles
    #(or stops, if then error is less than 0.01), and finally computes
    #the result file letters1.
    PerformActions:
    #
    NetworkFile: <OLD>
    #
    LearnPatternFile: <OLD>
    NoOfLearnParam: <OLD>
    LearnParam: <OLD>
    MaxLearnCycles: 100
    MaxErrorToStop: 1
    Shuffle: YES
    #
    ResultFile: letters2.res
    ResultMinMaxPattern: <OLD>
    ResultIncludeInput:  <OLD>
    ResultIncludeOutput: <OLD>
    #
    #This execution run continues the training of the already loaded file
    #for another 100 cycles before creating a second result file.
    #
    PerformActions:
    #
    NetworkFile: <OLD>
    #
    LearnPatternFile: <OLD>
    NoOfLearnParam: <OLD>
    LearnParam: 0.2 0.3
    MaxLearnCycles: 100
    MaxErrorToStop: 0.01
    Shuffle: YES
    #
    ResultFile: letters3.res
    ResultMinMaxPattern: <OLD>
    ResultIncludeInput:  <OLD>
    ResultIncludeOutput: <OLD>
    TrainedNetworkFile: trained_letters.net
    #
    #This execution run concludes the training of the already loaded file.
    #After another 100 cycles of training with changed learning
    #parameters the final network is saved to a file and a third result
    #file is created.
    #

\end{verbatim}
}

%\clearpage


The file $<$log\_file$>$ collects the SNNS kernel messages and
contains statistics about running time and speed of the program.
An example protocol file is listed in appendix~\ref{batchProt}.


\index{snnsbat!Log File}
If the  $<$log\_file$>$ command line parameter is omitted, {\tt
snnsbat} opens the file `snnsbat.log' in the current directory.
To limit the size of this file, a maximum of 100 learning cycles are
logged. This means, that for 1000 learning cycles a message will be
written to the file every 10 cycles. 

If the time required for network training exceeds 30 minutes of CPU
time, the network is saved. The log file then shows the message:

\begin{verbatim}
  #####  Temporary network file 'SNNS_Aaaa00457' created.  #####
\end{verbatim}

Temporay networks always start with the string `SNNS\_'. After 30 more
minutes of CPU time, {\tt snnsbat} creates a second security copy.
Upon normal termination of the program, these copies are deleted from
the current directory. The log file then shows the message:

\begin{verbatim}
  #####  Temporary network file 'SNNS_Aaaa00457' removed.  #####
\end{verbatim}

\clearpage

In an emergency (powerdown, kill, alarm, etc.), the current network is
saved by the program. The log file, resp. the mailbox, will later
show an entry like:

\begin{quote}
{\tt Signal 15 caught, SNNS V4.0 Batchlearning terminated.

SNNS V4.0 Batchlearning terminated at Tue Mar 23 08:49:04 1993\\
System: SunOS  Node: matisse  Machine: sun4m\\
Networkfile './SNNS\_BAAa02686' saved.\\
Logfile 'snnsbat.log' written.}
\end{quote}


\section{Calling Snnsbat}
\index{Example!snnsbat}
\index{snnsbat!Example}

{\tt snnsbat} may be called interactively or in batch mode. It was
designed, however, to be called in batch mode. On Unix machines,
the command `at' should be used, to allow logging the program with the
mailbox. However, `at' can only read from standard input, so a
combination of `echo' and `pipe' has to be used.

Three short examples for Unix are given here, to clarify the calls:

\begin{quote}
    unix$>$echo 'snnsbat mybatch.cfg mybatch.log' $\mid$ at 21:00 Friday 
\end{quote}

starts {\tt snnsbat} next Friday at 9pm with the parameters given in
mybatch.cfg and writes the output to the file mybatch.log in the
current directory.

\begin{quote}
    unix$>$echo 'snnsbat SNNSconfig1.cfg  SNNSlog1.log' $\mid$ at 22 
\end{quote}

starts {\tt snnsbat} today at 10pm

\begin{quote}
    unix$>$echo 'snnsbat' $\mid$ at now + 2 hours 
\end{quote}

starts {\tt snnsbat} in 2 hours and uses the default files snnsbat.cfg
and snnsbat.log

The executable is located in the directory
`.../SNNSv4.0/kernel/bin/$<$machine\_type$>$/'.\\ 
The sources of snnsbat can be found in the directory
`.../SNNSv4.0/kernel/sources/'.\\ An example configuration file was
placed in `.../SNNSv4.0/examples'.
