example/README: descriptions of example files.

The "example" directory contains some network files, pattern files and
screen files that might be useful for everyone.  You can use them (1)
just as examples to try when learning about the SunNet interface, (2)
to apply to some real tasks, or (3) as starting points to write your
own networks, etc., by modifying them.

The subdirectories "net", "pat", and "scr" contain network files,
pattern files, and screen files, respectively.  SunNet knows about
these subdirectory names, so you can stay in the "example" directory
and just type "network <file>" to read net/<file>, "pattern <file>" to
read pat/<file> and "screen <file>" to read scr/<file>.  SunNet always
looks for files first in the appropriate one of these subdirecotries
if it exists in the current directory, so it is convenient to organize
your directories this way.  The subdirectory "wts" which is empty is
the default subdirectory for reading in weight files.

Here are the files in each subdirectory and brief descriptions of them.

Network files in "net" directory:
--------------------------------

n.4.2.4		feedforward backprop net with 4 input 2 hidden 4 output units.
n.3layer	generic definition of 3 layer feedforward backprop net.
n.3layer.expr	same as above, but implemented with all expressions.
n.recur		3 layer feedforward backprop net with recursion at output.
n.jordan	Jordan's sequential network.
n.plot		for plotting error surfaces.
n.boltz		generic definition of boltzmann machine (3 layer).
n.boltz.full	fully connected boltzmann machine.
n.mft		generic definition of mean field theory net.
n.cl		competitive learning network.
n.td		temporal difference network (Rich Sutton's TD-1).
randomwalk	simple finite state machine used in n.td (just random walk among states.)

The files n.4.2.4, n.3layer, n.3layer.expr, n.jordan, n.cl, and
n.boltz.full are fully explained in the User's Guide.

The so called generic files "n.3layer", "n.boltz" and "n.mft" can be
used to construct different size networks from each.  Each of them has
the parameters "Nin", "Nhid", and "Nout" which specifies the number of
input, hidden, and output units, respectively.  For example, typing:

	network 'Nin=50 Nhid=12 Nout=36' n.3layer

(quotes around the arguments are necessary only when typing it
from a K-shell) will construct a feedforward backprop net with 50
input, 12 hidden and 36 output units.

In addition, the files n.boltz and n.mft have the parameter "Update"
which should be set to either SYNC (synchronous update) or ASYNC
(asynchronous update).  For example:

	network 'Nin=8 Nhid=5 Nout=6 Update=ASYNC' n.boltz

In the current implementation, asynchronous updating in these networks
is fairly slow, so synchronous updating might be prefered.  These
networks have not been tested extensively in terms of their
implementations and parameter choices such as the annealing schedule.
The basic implementation as well as the annealing schedules defined in
the files "schedule" (for n.mft) and "schedule.boltz" (for n.boltz)
are based on the article "A Mean Field Theory Learning Algorithm For
Neural Networks" by Carsten Peterson, et al. (MCC Technical Report
EI-259-87).  Suggestions for better implementations or schedules
would be appreciated.

The file "n.plot" for error surface plotting has detailed instructions
for its usage at the beginning of the file.

Pattern files in "pat" subdirectory:
-----------------------------------

p.encode4	4 patterns for the encoding problem with 4 input/output.
p.xor		XOR patterns.  output is the parity of 2 input units.
p.parity5	output is the parity of 5 input units.

p.encode4 is used in the User's Guide.

Screen files in "scr" subdirectory:
----------------------------------

scr.4.2.4	screen setup for 4-2-4 feedforward network.
scr.3layer	screen setup for generic 3 layer networks.

scr.4.2.4 is the screen file shown in the User's Guide.  scr.3layer can be
used with any of the 3 layer network files including n.4.2.4,
n.3layer, n.3layer.expr, n.boltz, and n.mft.

For example, if you would like to try the mean field theory network on
the 4-4 encoding problem with 3 hidden units, you might type:

	network 'Ninput=4 Nhidden=3 Noutput=4 Update=SYNC' n.mft
	pattern p.encode4
	screen scr.3layer

(Read the network/pattern files before the screen file.)  The screen file
scr.3layer will try to setup appropriate display of the weights and
activity patterns.  By default, these displays are updated after each
cycle during training.  To change how often the weights are displayed,
set the parameter 'display' to the number of cycles to be run between
updates.  Similarly, the parameter 'command' controls how often the
display of activities is updated because the display of activities is
done using the command list (clist).  

Some minor adjustments in this file might be necessary.  If the
weights seem to grow larger than can be displayed nicely, put a flag
"unit6.0" etc. or "normalize" at the end of each "dlist" command in
the file.  The X and Y ranges for the graph might need adjustment
depending on the magnitude of the error and how long it takes to
train.  To setup display for different size of the pattern set (other
than 4), see the instruction in the file.  Also, to properly draw the
picture of a feedforward network, comment out the line for drawing
backward connections as indicated in the file.
