#! /bin/csh -f
#################################################
## Tutorial : csh script for PlaNet tutorial.  ##
#################################################

###############################################
## Change these according to specific site.  ##
###############################################

set AUTHOR = miyata@dendrite.colorado.edu
### set this to email address of the person responsible for installing
### the programs who should be notified in case of installation problems.
set INSTALLER = # $AUTHOR

if( $?ARCH ) then
  unset ARCH; unsetenv ARCH
endif
# set ARCH = hp # set to machine architecture name if the
		# machine does not have the program arch.
		# eg. hp (for HP bobcats).

### XNet flags.  Set it as you like.
# set XNetARGS = '-fg black -bg white -font helvetica12'

###################################################
## Error handling - send mail to the installer. ###
###################################################
alias ERR 'set ErrMsg = \!* ; goto HandleError '

########################################
## Some primitive user interface .. ####
########################################
set SAY = /bin/echo
if( -x /usr/ucb/fmt ) set FMT = /usr/ucb/fmt
  
if( $?FMT ) then
  alias MSG '$SAY \\
\!* | $FMT'
else
  alias MSG '$SAY \\
\!* '
endif

if( -x /usr/ucb/more ) then
  alias MORE /usr/ucb/more
else if ( -x /usr/bin/more ) then
  alias MORE /usr/bin/more
else
  alias MORE more
endif

if( -x /usr/ucb/mail ) then
  set MAIL = /usr/ucb/mail
else if ( -x /bin/mail ) then
  set MAIL = /bin/mail
else
  set MAIL = mail
endif

MSG  "		Welcome to PlaNet Tutorial \!\!"

#########################################
## Check if it's the right directory.  ##
#########################################

if( ! -d src ) then
  ERR "I cannot find the source directory src in this directory ($cwd).  Please run\
me from the main directory."
endif
set DIR = $cwd

#######################################
## Find out what machine we are on.  ##
#######################################

if( $?ARCH ) then
  $SAY ARCH=$ARCH
else if( -x /bin/arch ) then
  set ARCH = `/bin/arch`
else if( -x /usr/bin/arch ) then
  set ARCH = `/usr/bin/arch`
else if( -x /usr/local/bin/arch ) then
  set ARCH = `/usr/local/bin/arch`
endif

if( ! $?ARCH ) then
	ERR "Program arch not available.  Please set the variable\
ARCH in me to the name of the architecture and run me again."
endif

set HOST = `hostname`

$SAY -n "Your machine $HOST is a $ARCH, "

if( $ARCH == hp ) then
  alias SAYN "/bin/echo \!* '\c'"
else
  alias SAYN "/bin/echo -n"
endif

###########################################
## Check which window system we are in.  ##
###########################################
if( $?WINDOW_ME ) then
  $SAY "and your window system is suntools."
  set PROG = SunNet
else if( $?DISPLAY ) then
  $SAY "and I assume your window system is X (with server $DISPLAY)."
  set PROG = XNet
else
  MSG  "	Please run in either suntools or Xwindow environment.  When\
running under Xwindow, set environment DISPLAY to the X server\
and run 'xhost $HOST' on the server machine."
  exit
endif

$SAY "For this configuration, we are going to use the program $ARCH/$PROG.\
"

#############################################
## Install the main program if not there.  ##
#############################################

unset ErrMsg
if( ! -d $ARCH ) mkdir $ARCH
if( ! -x $ARCH/$PROG ) then
  $SAY "Invoking 'Install $PROG'"
  $DIR/Install $PROG
  if( $status ) set ErrMsg = "cannot install program $cwd/$ARCH/$PROG"
endif
if( $?ErrMsg ) goto HandleError

#########################################
## Make sure we can use 'netcommand'.  ##
#########################################

set COM = $DIR/$ARCH/netcommand
if( ! -x $ARCH/netcommand ) then
  $SAY "	Installing $ARCH/netcommand ..."
  cc netcommand.c -o $ARCH/netcommand
endif
if( ! -x $ARCH/netcommand ) then
  ERR "cannot install $DIR/$ARCH/netcommand"
endif

alias netcommand $ARCH/netcommand	# this should be faster.

#####################################################
## If from suntools, make sure we are in gfxtool.  ##
#####################################################

if( $?WINDOW_ME ) then
 if( $WINDOW_ME == $WINDOW_GFX ) then
    MSG  "	Please run from a graphics tool window.  It can be opened\
by selecting 'gfxtool' from the SunView Root Menu."
    exit
 endif
endif

##############################################################
## Make sure we are authorized to connect to the X server.  ##
##############################################################

if( $PROG == XNet ) then
  set X = `xhost` ; if( $status == 0 ) goto OK
  MSG  $X
  MSG  "	Tutorial: We cannot connect to the X server. Please run 'xhost\
$HOST' on the server machine and run this Tutorial again."
  exit;
endif

##########################################################################
## Secure a command port.  Use planet.port (default) or port.tutorial.  ##
##########################################################################

if( ! $?NETPORT ) setenv NETPORT $HOME/planet.port
test -f $NETPORT
if( $status == 0 ) then
  MSG  "	Tutorial: It appears the default command port $NETPORT\
is in use.  We'll use 'port.tutorial' instead."
  MSG  "	setenv NETPORT $HOME/port.tutorial"
  setenv NETPORT $HOME/port.tutorial
  test -f $NETPORT
  if( $status == 0 ) $COM quit &
  sleep 2
  test -f $NETPORT
  if( $status == 0 ) /bin/rm $NETPORT
endif

##############################
## Start the main program.  ##
##############################

MSG  "\
\
	Tutorial: Let's run $ARCH/$PROG in the background.  Hit RETURN."
SAYN "shell> $ARCH/$PROG &"
set INPUT = $<
$ARCH/$PROG > /dev/null &

OK:

MSG  "\
\
	Tutorial: Let's source the program RunNet.  Hit RETURN."
SAYN "shell> source $DIR/RunNet"
set INPUT = $<
if( $PROG == XNet ) then
  MSG  "	Place $PROG by moving the mouse and clicking a button."
endif
setenv NETPROG $PROG
source $DIR/RunNet

if( $PROG == XNet ) then
  SAYN "Hit return when ready: "
  set INPUT = $<
endif

##################################################
## Set up various macros for user interaction.  ##
##################################################

## alias PROMPT 'SAYN "section $SECTION: "'
alias PROMPT 'SAYN "try: "'
alias USER 'PROMPT ; set INPUT = $< ; if( "$INPUT" == exit ) goto END;if( "$INPUT" == section ) goto Menu ; if( $LogIt ) $SAY "$INPUT" >> $LogFile'

alias WAIT 'SAYN "hit RETURN to go to next section: " ; set INPUT = $< ; if( "$INPUT" == exit ) goto END ; if( "$INPUT" == section ) goto Menu '

alias StartSection '@ SECTION = \!:1; clear; set PREVIOUS = Section$SECTION; MSG  "	Section $SECTION. \!:2*. "; MSG  " "; if($?LogIt) $SAY Section $SECTION >> $LogFile'

alias TRY 'set RETURN = \!:1 ; goto TryOut '
alias SHOW '$SAY ""; SAYN "example>> " \!*; set INPUT = $<; $COM \!* ; $SAY ""'
alias SHOW.PAGE '$SAY ""; SAYN "example>> " \!*; set INPUT = $<; $COM \!* | MORE'
alias CheckNet 'set GOTO = \!:1 ; goto SetupNetwork '

set NetFile = n.4.2.4
set PatFile = p.encode4

##########################################################
## Create Log file to be mailed at the end of session.  ##
##########################################################

set LogDir = /tmp
if( -w $LogDir ) then
  set LogFile = $LogDir/planet.log.$USER
  $SAY Start: `/bin/date` >! $LogFile
  set LogIt = 1
else
  unset LogIt
endif

####################################
## Check if the socket is working ##
####################################

MSG  "	Let me first check if we can talk to $PROG..."

$COM whatis eta > /dev/null
if( $status != 0 ) then
  if( $PROG == XNet ) $SAY "$PROG may not be connected to your Xserver.\
Check the environment 'DISPLAY' and/or run 'xhost'."
  ERR "I cannot talk to $PROG."
endif

#############################################
## Define method for locating window/graph.##
#############################################

if( $PROG == SunNet ) then
  set MouseMethod = "clicking a mouse button at two opposite corners of the region"
else 
  set MouseMethod = "depressing a mouse button at one corner of the region and releasing it at the opposite corner"
endif

$COM alias nset set	# use 'nset' instead of 'set'.

###############################
## Now, Start the tutorial.  ##
###############################

MSG  "	OK.  It appears that $PROG is running and you can send\
command to it. Let's begin the tutorial\!\!\
"
goto OK1

MSG  "	We first need to run the script 'netcsh'.  Hit RETURN."
SAYN 'shell> source netcsh'
set INPUT = $<
source ./netcsh > /dev/null
MSG  "	This script sets up aliases for all $PROG commands so that we can run\
them from the shell.  (Run '. netkorn' when you use ksh instead of csh.)"

OK1:

MSG  "	Next, let's go to the 'example' subdirectory.  We will\
use some of the files in this directory."
SAYN 'shell> cd example; pwd'
set INPUT = $<
cd example; $COM cd $cwd; pwd

SAYN "Hit RETURN to see the table of sections: "
set INPUT = $<

Menu:
clear
@ SECTION = 0
$SAY "\
Table of sections\
1. Introduction & Simple Commands - 'help' and 'nset'\
2. Setting up Network and Patterns - 'network' and 'pattern'\
3. Running the Network - 'present' and 'cycle'\
4. Plotting Learning Curve - 'graph'\
5. Opening Windows - 'window'\
6. Displaying Network States - 'display'\
7. Making Display Easy - 'dlist'\
8. Displaying Network Responses - 'response'\
9. Command List - 'clist'\
10. Plotting Error Surface - file 'n.plot'\
11. Printing Network States - 'print' and 'printlist'\
12. Screen Specification File - 'screen'\
13. Saving Network States - 'savefile' and 'save'\
"
SAYN "Please enter a section number you would like to start: "
set INPUT = $<
while( "$INPUT" > 13 || "$INPUT" < 1 )
  SAYN "Please enter a section number between 1 and 13."
  set INPUT = $<
end
if( "$INPUT" > 2 ) then
  CheckNet Section$INPUT
endif
goto Section$INPUT

Section1:
StartSection 1 Introduction and Simple Commands - 'help' and 'nset'

MSG "	This tutorial goes through an example $PROG session in\
which you will construct a small three layer network, and\
train the network using the back-propagation algorithm.\
You interact with $PROG through a command-based interface.\
There are currently about 40 $PROG commands, about half of which\
you will learn about as we go through this tutorial.  These\
commands will allow us to set up and train a network and to create\
some graphic displays of the learning curve, activity\
patterns, weight matrices, and error surfaces."

MSG "	Let's try sending a command to $PROG.  It's a useful\
one.  Simply hit RETURN after 'example>> help' below."

SHOW help

MSG "	You just entered the command 'help'.  It was sent to $PROG,\
and $PROG, in response, printed all the command names.\
The syntax and an explanation about the use of a command\
can be obtained by typing help <command name>.  Let's try this."

SHOW help help

MSG "	At this point, you have several options.  When you see a prompt\
like below, you can type in any $PROG command you would like to try\
(so far, 'help' is the only one you know about.)\
Or, type 'next' or 'n' to proceed to the next instruction, \
'again' or 'a' to repeat the previous instruction,\
'section' or 's' to see the table of sections and go to a different section,\
or 'end' or 'e' to end this tutorial.\
Type '?' if you need this information."

TRY help
help:

MSG "	You can type 'help <command name>' to get more\
detail description of a command any time during this\
tutorial."

MSG "	Let's try another useful command.\
The command 'nset', with no arguments, prints all the \
parameters that you can set, with a short description and the current\
value of each.  'nset' is equivalent to 'set' but 'nset' is preferred because\
it does not conflict with the shell command 'set'."

# There are a large number\
# of parameters - more than can be displayed in this window. "#  To keep the\
# display from scrolling away, before you hit RETURN,\
# press the right mouse button and choose 'Enable Page Mode'.  This makes\
# print out to stop "

SHOW.PAGE nset

MSG "	Some often-used parameters are eta (learning rate) and alpha\
(momentum) for back-propagation learning.  To print the values of\
some parameters, use the command 'whatis' with the parameter name(s) as the\
argument(s)."

SHOW whatis eta alpha

MSG "	A parameter can be set by 'nset <parameter name>\
<parameter value>'. You can set multiple parameters."

SHOW nset eta 0.2 alpha 0.4
SHOW whatis eta alpha

MSG "	Try 'nset' and 'whatis'.  Type 'next' or 'n' when you are done."

TRY set
set:

MSG  "\
	Now we are ready to try some commands to actually\
build a network in Section 2."

WAIT

Section2:
StartSection 2 Setting Up Network and Patterns - 'network' and 'pattern'

MSG  "	Typically, the first thing you do in a $PROG session\
is to set up a network and a set of input/output patterns\
by reading in a network file and a pattern file."

MSG  "	The command 'network' reads in a network file and the\
command 'pattern'  reads in a pattern file.  Both take a\
file name as an argument.  Let us use  here a 4-2-4\
encoding network defined in the file $NetFile and the\
patterns  defined in the file $PatFile in the example\
directory."

MSG "	Let's set up the network."

SHOW network $NetFile
if( $status & ! -f net/$NetFile ) then
    ERR "network file net/$NetFile is missing."
endif

MSG "	This file specifies everything we need to run a\
back-propagation network.  Let's check to see that the network has been\
constructed properly now in $PROG."

SHOW names layer

MSG "	These are the names of the layers in the network\
defined in this file and the number of elements in them.\
The 'Input' layer has 4 units, 2 units in  the 'Hidden'\
layer, and 4 units in the 'Output' layer.  Also,"

SHOW names connection

MSG "	These are the names of connections (sets of weights)\
in the network. 'InputHidden' connects from the layer\
'Input' to the layer 'Hidden' and so has 4 by 2 matrix of\
weights.  'HiddenOutput' connects from the layer 'Hidden'\
to the layer 'Output' and so has 2 by 4 matrix of weights."

MSG "	To set up a feedforward network of a different size,"

SHOW network Nin=3 Nhid=4 Nout=5 n.3layer
SHOW names layer
SHOW names connection

MSG "	The file 'n.3layer' contains a generic definition of 3 layer\
back-propagation networks which you can use to construct different size\
networks by specifying the number of Input (Nin), Hidden (Nhid) and Output\
(Nout) units.  Try constructing different networks."

TRY network
network:

MSG "	We will use this one for this tutorial."

SHOW network n.4.2.4

MSG "	This is equivalent to 'network Nin=4 Nhid=2 Nout=4 n.3layer'."

MSG "	The layers and the connections basically define the\
'structure' or the 'architecture' of the network.\
The 'function' of the network is defined by what are\
called 'procedures'."

SHOW names procedure

MSG "	These are the names of the 'procedures' also defined in\
the file $NetFile.  These define the network as a\
feedforward back-propagation network.  The content of a procedure\
can be examined by:"

SHOW listproc activate

MSG "	The prodcedure 'activate' is used to present an input\
pattern to the network, propagate activities forward to\
compute an output pattern which is then compared to the\
corresponding target pattern to compute the output error."

SHOW listproc learn

MSG "	The procedure 'learn' is used to train the network by\
back-propagating the error through the network and\
modifying the weights."

MSG "	These procedures are written in $PROG's Network\
Specification Language.  Learning about this language is not\
necessary for this tutorial.  It is fully explained in the User's Guide\
and in the Reference Manual.\
If you would like to know about the two procedures used in this\
network, use 'listproc' to see the content of a procedure and\
type 'help forward' etc., to find\
out what each command in the procedure (called an action)\
does.  Or you can skip it (type 'next' or 'n') for now and just\
learn how to run the network already given in the file."

TRY procedure
procedure:

MSG "	Now that we have the network set up, let's read in the\
pattern file for the encoding task."

SHOW pattern $PatFile
if( $status & ! -f pat/$PatFile ) then
    ERR "pattern file pat/$PatFile is missing."
endif

# MSG "	The content of the file '$PatFile' and its content looks like\
#"
# cat $PatFile

MSG "	In the encoding problem, the desired output is the same\
as the input: when the network is trained on a set of\
patterns, it needs to develop internal representation (or\
features) in the hidden units that can encode all the\
patterns and then to decode them out into the output units.\
The file we have just read in consists of four pairs of\
input/target patterns: for each pair the input and target\
have identical pattern in which one of the four input/output\
units is turned on and the other three are turned off."

MSG "	Now with the network and the patterns defined, we are\
ready to run and train the network with the patterns."

WAIT

CheckNet Section3
Section3:
StartSection 3 Running the Network - 'present' and 'cycle'

MSG "	Once a network file and a pattern file have been read\
into $PROG the network can be run.  Running this\
back-propagation network involves two steps: (a) presenting\
a pair of input/target patterns to the network (i.e.,\
putting them into the input/target buffers) and (b)\
executing a procedure defined in the network file."

MSG "	The command 'present' does these for a single\
input/target pair. For example, try this.  (It may\
take a while since $PROG needs to prepare a look-up table\
for the logistic function.)"

SHOW present 0

MSG "	'Present 0' presents the first input/target pattern\
pair, executes the procedure 'activate', and print the\
output error value. To specify a procedure other than\
'activate', type 'present 0 <procedure name>', such as, 'present 0 learn'."

MSG "	Try 'present 1', 'present +', 'present -', 'present\
1-3', 'present all', and so forth. Type 'help present' for\
more information on this command."

TRY present
present:

MSG "	The error printed for each pattern is computed by\
averaging the square errors across the output units.  Our\
network has not been trained, so the errors printed are\
probably large.  So, let us start training the network\
using another command 'cycle'."

MSG "	The command 'cycle' cycles through all pairs of \
input/target patterns and executes a procedure for each\
pair, and repeats this process for a given number of times.\
Let's try 'cycle 50'.  $PROG will cycle through all pairs of\
patterns 50 times, executing the procedure 'learn' (the\
default procedure for the command 'cycle') after\
presentation of each pair."

SHOW cycle 50

MSG "	What is printed during 'cycle' indicates how many\
cycles have been run, and the overall error averaged across\
all the patterns.  The parameter 'print' specifies how\
often this information should be printed.  Type 'nset print\
10', and try cycle 50 again.  $PROG will now print the\
error information at every 10 cycles."

TRY cycle
cycle:

MSG "	If 'print' is set to zero, nothing will be printed."

MSG "	In this section you have learned how to run the\
network with the commands 'present' and 'cycle'.  But these commands provide\
only minimal feedback about what is going on.  In the\
following sections, we will look at ways to get more and\
more useful  information."

WAIT
CheckNet Section4
Section4:
StartSection 4 Plotting Learning Curve - 'graph'

MSG "	While running the network with 'cycle', it is useful to\
plot the learning curve, that is, error as a function of\
learning cycles. First, reinitialize the network (this\
means to clear all units and to randomize all weights) by:"

SHOW network reset

MSG "	and then initialize a graph by typing 'graph new', and\
specifying some necessary\
information in response to $PROG's prompts.  For now, just\
hit return after each prompt to get the default graph (X\
ranges from 0 to 300 [or the current step number and 300\
steps plus that], and Y ranges from 0 to 0.1 [error]).  "

SHOW graph new

MSG "	After a graph is initialized, the average square error\
is plotted in the graph at every N learning cycles, N\
being specified by the parameter 'graph' (default = 1).\
Now watch how the error decreases."

SHOW cycle 300

MSG "	More than one learning curve can be plotted in the same\
graph. Initialize the network by 'network reset same' (this\
gives the same initial weights as the previous one), and change\
some learning parameters, say, eta (the learning rate) to\
0.4 and alpha (the momentum factor) to 0.8 ('nset eta 0.4\
alpha 0.8'), and run the network again with 'cycle 300'.  "

TRY cycle2
cycle2:

MSG "	This network usually converges much more quickly with\
these parameter values - compare the two learning curves in\
the graph."

MSG "	A graph can plot not just errors but actually any\
values in the network.  This is done with the command\
'glist' which adds an item to be plotted in so-called the\
'graph list'.  For example:"

SHOW glist clear
SHOW glist \$err"[0] 0" 

MSG "	This specifies the error for the first pattern to be plotted. \
The second\
argument '0' specifies the character to be used to mark the\
plotted curve.  To set up a graph list for all four patterns."

SHOW glist \$err"[1] 1"
SHOW glist \$err"[2] 2"
SHOW glist \$err"[3] 3"

MSG "	To check the current graph list:"

SHOW glist

MSG "	Set the parameter 'mark' to say, 50 (so curves are marked\
at every 50 steps), reset the network with 'network reset',\
clear the graph with 'graph clear', and run 'cycle 300' again.\
Repeat this a few times if you want.  You may want to set 'print'\
to 100 so this instruction won't scroll away."

TRY glist
glist:

MSG "	In this section, you have learned how to plot the\
learning curve - errors as a function of training cycles.\
In the next section, we will look more closely into what's\
happening inside the network."

WAIT
CheckNet Section5
Section5:
StartSection 5 Opening Windows - 'window'

MSG "	In $PROG you can examine the state of the network by\
displaying various sets of values in the network, such as\
activation patterns in layers, or weights in connections.\
These values are displayed in windows you open in the\
display area. "

set graphOpen = `graph command`	# if a graph is open we need to move it.
if( $#graphOpen ) then

MSG "Before opening some windows in our current\
example, however, the graph should be either moved or\
closed to make room in the display area for the windows.  To\
move the graph, type 'graph move' and select a rectangular\
region in the display area for moving the graph to by $MouseMethod."
MSG "	Move the graph to either the left or the right\
half of the display area so that you can open windows in\
the other half.  The current graph will be erased and then\
reappear at the new location."

SHOW graph move

MSG "	Want to try again? (if you're satisfied, just type 'n')"

TRY move
move:

unset graphOpen
endif	# graphOpen

MSG "	The command 'window' is used to open windows.  Probably\
the easiest way to open a number of windows is 'window NxM'\
which opens N times M windows and arrange them in N rows\
and M columns in the display area."
MSG "	Let's open twelve windows by typing this, and then\
selecting a rectangular region in which to open the\
windows with the mouse."

SHOW window 4x3

MSG "	Every window is given a number which is used to refer\
to that window when something is to be displayed in it.  We\
will use these windows when we display network states in\
them in the next section. Type 'help window' for more about\
what you can do with windows, e.g., erasing, framing, etc."

TRY window
window:

MSG "	In the next section, we will display some network\
states in the windows we just opened."

WAIT
CheckNet Section6
Section6:
StartSection 6 Displaying Network States - 'display'

set windowOpen = `netcommand window`
if( $windowOpen[1] == 0 ) then
MSG "	We first need to open some windows.  Hit RETURN and select a\
rectangular region in which to open the windows by $MouseMethod."

SHOW window 4x3

endif # windowOpen

MSG "	There are two basic commands for looking into the state\
of the network: 'display' and 'response'.  The command\
'display' displays a vector (such as the activation pattern\
in a layer) or a matrix (such as a weight matrix) in a\
window.  The command 'response' displays responses of a\
vector or a matrix to all the patterns in the pattern file.\
We will start with the simpler of the two, 'display'"

MSG  "	When you display something with 'display', you specify\
(a) what you want to display and (b) in which window you\
want it displayed.  For example, you can display the\
activation pattern in the layer 'Output' into window 1 by:"

SHOW display Output window1

MSG  "or simply" 
SHOW display Output w2

MSG  "	Specifying a layer name like 'Output' refers to the\
activation values of the units in that layer.\
In the display, a black square represents a positive\
value, a white one a negative value (these are reversed if the background\
color is black, or different colors may be used on a SUN with a\
color monitor), and the size (area) of the square\
represents the absolute value."
MSG "	Actually, you don't have to give a window #. Just click\
a mouse button inside any window."

SHOW display Output

MSG  "Try displaying activations in different layers in \
different windows.  Type 'names layer' to find out the names\
of the layers."

TRY display
display:

MSG "	You can also display various components of a layer.\
For example:"

SHOW display Output:net 

MSG "	This displays the net inputs in the Output units.\
Net inputs can be larger than 1.0 and the display of them\
may overlap with each other.  To avoid this do:"

SHOW display Output:net normalize

MSG "	The flag 'normalize', which can be shortened to 'norm' or just\
'n', normalizes the values before displaying them."
MSG "	Similarly, Output:bias is the biases and Output:delta is\
the deltas (errors) in these units."

TRY dispComp
dispComp:

MSG "	You can also display a part of a layer."

SHOW display 'Output:net[0->2]' unit5

MSG "	This displays the net inputs of the first 3 units in the\
Output layer.  The flag 'unit5' means to take 5 as the unit value\
for the display.  In other words, the values are divided by 5 before\
they are displayed.  This flag can also be abbreviated to its first\
characters - 'un5' or 'u5'."

MSG "	You can also display a weight matrix by specifying its\
connection name as the first argument to 'display'.  For\
example"

SHOW display InputHidden normalize

MSG "	Normalizing is often necessary when displaying weights.\
Each row displays the weights going into one of\
the units receiving the connection, including the bias for\
the unit which is displayed  on the right most column."
MSG "	Try displaying HiddenOutput too."

TRY displayWeight
displayWeight:

MSG "	There are a number of flags that you can give to the\
'display' command to change the way the display appears on\
the screen.  Type 'help display-flags' and try some of the\
flags described."

TRY displayFlags
displayFlags: 

MSG "	You can display not just activation patterns or weight\
matrices but an arithmetic expression. For example:"

SHOW display "logistic(Output:net+Output:bias)"

MSG "	This is the sigmoid function used to compute the activation\
values from the net inputs and the biases.  Display the activation\
values in an adjacent window and compare the two."

SHOW display Output

@ SECTION++
MSG "	Try displaying more explicit form of the same sigmoid function\
'1/(1+exp(-Output:net-Output:bias))' if you want.  By the way, the rest of\
this section will show more and more complex examples of expressions.\
If you want to skip it for now, type 'section' and go to section\
$SECTION.\
Learning about expressions is not essential at this point, but \
can be useful if you are thinking of constructing your own network\
because expressions are the most fundamental level of $PROG's \
Network Specification Language in which the operation\
of a network is specified.  Also, many $PROG commands understands\
and evaluates expression as 'display' does.  Remember that an expression\
argument to 'display' cannot contain white spaces.\
"
@ SECTION--

TRY dispExpr
dispExpr:

set Thresh = `$COM print "average(abs(InputHidden))" p2`

MSG "	An expression can contain comparison operators."

SHOW display "(abs(InputHidden)>=$Thresh)*InputHidden" n

MSG "	This will display only those weights in InputHidden with\
absolute values greater than or equal to $Thresh.  To see how this works try:"

SHOW display "abs(InputHidden)>=$Thresh"

MSG "	This expression generates another matrix of the same size\
as the original matrix but its elements are either 1 or 0 depending\
on whether or not the corresponding elements in the original matrix\
have absolute values greater than or equal to $Thresh.  When\
the original matrix is mutiplied element-by-element by this new matrix\
the result is that all the elements that are less than $Thresh\
are turned to zeros."

MSG "	Most operators such as '+', '-', '*', '/', and the comparison\
and logical operators by default work in an\
element-by-element fashion.  That is, they take two objects of a same\
size and generate another object of the same size by performing the \
operation on every pair of corresponding elements in the original objects.\
They can also be applied to two objects of different dimensions.  For example,\
'scaler*vector' does what you would expect - it multiplies each element\
of the vector by the scaler.  Experiment with these."

TRY dispExpr2
dispExpr2:

MSG "	There is another operator '**' that performs matrix \
multiplication in the usual way - not in element-by-element fashion.\
For example:"

SHOW display 'InputHidden**HiddenOutput' normal

MSG "	computes the product of the two weight matrices.  Of course\
a vector is a special case of a matrix.  For example:"

SHOW display 'HiddenOutput**T(Hidden) unit5'

MSG "	is the vector matrix product which is performed when\
the Hidden activations are propagated through the HiddenOutput weights\
to compute the net inputs in the Output units.\
To see this, display the following in a window next to the previous\
one and compare the two:"

SHOW display Output:net unit5

MSG "	If you are interested in learning more about what kinds of\
expressions $PROG understands,\
type 'help vector' and 'help expression'.  Feel free to try as\
many examples as you want."

TRY dispExpr3
dispExpr3:

MSG "	This is the end of our little excursion into the power of\
the $PROG language.  Let's get back on track and learn more about\
the $PROG interface features."

WAIT
CheckNet Section7
Section7:
StartSection 7 Making Display Easy - 'dlist'

MSG "	Often it is useful to observe a set of network states\
periodically while you are training a network.  A convenient\
way to do this is to use the command 'dlist' to put the\
things you want to display in the display list $PROG keeps\
of the items to be displayed.  The command 'dlist' takes\
exactly the same set of arguments and flags as 'display', for\
example:"

SHOW dlist clear
SHOW dlist Input window1 column1

MSG "	The resulting display specification is put into the display \
list for later use instead of being displayed immediately.\
The items in the display list can be displayed simply\
by typing"

SHOW display

MSG "	Let's set up a disply list for our three-layer network\
by first opening 6 windows (place them so they don't overlap\
with the graph), and then typing in these:"

SHOW window erase
SHOW window 3x2
SHOW dlist InputHidden window2 transpose unit6.0 
SHOW dlist Hidden window4 column2 
SHOW dlist HiddenOutput window6 unit6.0 
SHOW dlist Output window5 column1

MSG "	The items in the display list can be displayed simply\
by typing"

SHOW display

MSG "	Note that this is a configuration of display matrices\
in which rows or columns of adjacent matrices that have\
meaningful relations are lined up (approximately) with each\
other so that it is easy to see the flow of information in\
the network.  For example, the display of the activation\
value of each Output unit in the upper-left window is lined\
up with a corresponding row of the HiddenOutput weight\
matrix displayed to its right, which represents the weights\
going into that Output unit and the bias of that unit."

MSG "	The items in the display list are also displayed\
automatically when the command 'present' or 'cycle' is\
executed.  For the command 'present', the items are\
displayed after presentation of each pattern. "

SHOW present all

MSG "	If the parameter 'display' is set to a positive integer\
N (default = 1), the items in the display list are\
displayed at every N cycles while the command 'cycle' is\
being run.  The network's response to the last pattern presented will\
be displayed after each cycle."

SHOW cycle 10

MSG "	If 'display' is set to 0, there is no display."
MSG "	Try 'present' and 'cycle' or you can change the display list\
by 'dlist clear' and then typing in new items with 'dlist'.\
If the display is too slow during 'cycle', increase the value of 'display'."

TRY dlistPresent
dlistPresent:

MSG "	The command 'display' and 'dlist' are quite useful, especially\
with the ability to evaluate and display arbitrarily complex expression.\
The next command 'response' extends the 'display' command\
even further by combining it with the command 'present' which\
can present patterns and execute a procedure."

WAIT
CheckNet Section8
Section8:
StartSection 8 Displaying Network Responses - 'response'

MSG "	You may want to see the responses of the network to all\
the patterns at once, instead of seeing only the response\
to one pattern at a time.  The next command 'response'\
presents to the network a set of input/target pairs, and\
for each pair it executes a procedure and then displays the\
response of a vector to each pair in a display matrix,\
arranging all the display matrices properly in a window.  For\
example:"

SHOW response Output win5

MSG "	As for 'display', the first argument is a vector or\
connection name or an expression.\
The default procedure for 'response' is 'activate', as is for the command\
'present'.  This can be changed by an optional second argument.\
We just used the default procedure 'activate'.\
A window in which to display the responses\
should be specified either by giving a flag as in the above\
example, or by clicking a mouse button in a window."

MSG "	This example displays activation pattern in the Output units\
for the four patterns in four display matrices arranged in\
a 2 by 2 matrix.  Note that there is a hierarchy of\
matrices: the small display matrices (with only one row in this case)\
are arranged in a big matrix (with two rows and two columns) of matrices.\
Each small matrix is one of the four Output patterns.\
The numbers of columns for the\
small and big matrices can be controlled separately."

SHOW response Output w5 Column4 column1

MSG "	The flag 'column1' specifies, as for the command 'display',\
the number of columns in each (small) display matrix.  The flag\
'Column4' specifies the number of columns in the (big)\
matrix of display matrices."
# If it is missing,\
# the default number of columns for the big matrix is determined\
# so that it has approximately a same number of columns and rows."

MSG "	Type, for example 'response Hidden w4 C1 c2', and 'response\
Input w1 C4 c1'.  (If the Hidden activations are displayed too small,\
suppress the display of the labels by adding a flag '-label'.)\
Combined with the disply of the weights\
in the display list created with 'dlist', these commands\
will create a display matrices whose configuration allows\
rows or columns of different matrices that have meaningful\
relations to line up with each other.  Or try a different configuration."

TRY respNet
respNet:

MSG "	Compare the response of the output units with the input\
patterns.  The network is trying to learn to\
produce the same pattern at the output units as at the\
input.  If they are not very close, then the network needs\
some more cycles of training.  If we run 'cycle' now\
the display list we have set up would display the two weight\
matrices and the activation patterns in the three layers\
in response to a single pattern.\
However, it would be more useful to display responses to\
all the patterns, like we have just done with the command 'response'.\
We will see how to do so in the next section."

WAIT
CheckNet Section9
Section9:
StartSection 9 Command List - 'clist'

MSG "	Although there is no 'response list', $PROG has a\
more general one, namely the command list which keeps a set\
of commands together with their arguments and lets you\
execute all or some of the commands whenever desired.  The\
command 'clist' stores a command and a set of arguments in\
the command list."

MSG "	 Let's set up a command list by typing:"

SHOW clist clear
SHOW clist response Hidden window4 Column1 column2 -label
SHOW clist response Output window5 Column4 column1

MSG "	Type 'clist' to print out the content of the command\
list.  You can execute some or all items in the list by\
typing 'clist do 1', 'clist do 1 2', 'clist do all', and so\
forth.  You can change the command list by 'clist clear' and\
typing in new items."

TRY clistDo
clistDo:

MSG "	Let's use this command list to monitor the performance\
of our network while running 'cycle'.  \
If the parameter 'command' is set to N (>0), the commands\
stored in the list will be executed at every N steps.\
Because each learning step will not change the network state\
very much, we do:"

SHOW nset command 20 display 20

MSG "	Also, turn off the items in the display list for displaying\
activation patterns by"

SHOW dlist - 1 3 5

MSG "	because we are using these windows for the responses instead."

MSG "	We can use the unused window #3 by, for example:"

SHOW echo 3 Training 4-2-4 Encoding Network.

MSG "	Now, reset the network, clear the graph, and let's run some\
more training cycles by 'cycle\
300' and observe how the weight matrices and the responses\
of the three layers develop as the training proceeds.  Feel free\
to change dlist and clist items or other parameters. \
Run 'cycle 300' a few times (resetting the network and clearing the\
graph each time).\
Examine the solution reached by the network each time - how do the Hidden\
units encode the patterns?  Also, compare the two weight matrices."

TRY clistRun
clistRun:

WAIT
Section10:
StartSection 10 Plotting Error Surface - file 'n.plot'

MSG "	Besides the graph, which plot values against the number of\
training cycles, $PROG provides a basic two-dimensional plotting\
capability which plots a number of points defined by two vectors\
- a vector for X values and another vector for Y values.  Instead of\
explaining how to use the plotting commands, let us look at an\
interesting use of this feature in plotting of error surfaces.\
This is an example of application procedures written in $PROG's\
Network Specification Language which make use of the plotting commands."

MSG "	An error surface is defined as the error of the network as a\
function of all the weights in the network.  While we cannot display\
such a high dimensional image, we can look at small slices of it by\
picking a pair of weights and varying only these weights while fixing\
all the other weights constant and measuring how the error changes as\
a function of the two weights."

MSG "	To set up the error surface plotting, read in the network file\
'n.plot' by typing:"

SHOW network + n.plot

MSG "	Don't forget the '+', or you will delete the current network.\
'+' means this is an additional network specification.  This file\
defines a few procedures for computing the error surface, and then\
sets up a list of plot items that actually plot the error surface."

MSG "	The next step is to open a number of plot areas in which to do\
plotting.  First we erase the windows to make room for the plotting."

SHOW window erase

MSG " and turn off the display and command list."

SHOW dlist - all
SHOW clist - all

MSG "	Open plot areas by typing the following, for example,\
and selecting the region created by erasing the windows by $MouseMethod"

SHOW plot 2x2

MSG "	This opens four plot areas arranged in a 2 by 2 matrix. \
To prepare the error surface you run the procedure 'sweep' with arguments \
specifying which two weights to vary (this may take a while):"

SHOW exec 'sweep(InputHidden[0][0],InputHidden[0][1])'

MSG "	'Exec' is a command that simply executes procedures given as\
its arguments.  I will explain about the procedure 'sweep' in a moment."
MSG "	Finally you generate the plot on the screen by:"

SHOW plot 1 new

MSG "	This is a 3-d image of the error surface.  The height of\
each point represents the error for particular values of the two\
weights, which are represented by two horizontal axes one running from\
left to right and the other running perpendicular to it."
MSG "	The '@' mark in the plot tells you where the current values\
or the weights are.  The network is trying to find the lowest point \
on the surface (where the error is the smallest)."

MSG "	The procedure 'sweep' computes the error surface by varying\
the two weights specified and computing the errors for different weight\
values.  This creats the 3-d image. "

MSG "	There are a variety of ways to manipulate this 3-d image.\
Let's try some of them.  First change the plot to use by:"

SHOW plot 2 new

MSG "   For example, you can scale the image by:"

SHOW exec 'scale(3.0)'

MSG "   Or rotate it by:"

SHOW exec 'rotate(20,60)'

MSG "   This means to change the horizontal viewing angle to 20 degrees\
(measured from the center to the right) and the vertical viewing angle\
to 60 degrees.  The default angles were -10 degrees horizontal and\
30 degrees vertical (as in the first plot)."

MSG "	You can zoom into a part of the plot by:"

SHOW exec 'zoom(2)'

MSG "	And unzoom it by:"

SHOW exec unzoom

MSG "   Try scale(), rotate(), zoom(), and unzoom() to manipulate this\
image of the surface, or try varying different pairs of weights as\
well with 'exec sweep(weightX,weightY)'."
MSG "   Also, try plotting the error surface of the XOR problem which can\
take some very interesting shapes.  You can do this by (1) constructing a 2-2-1\
network with 'network Nin=2 Nhid=2 Nout=1 n.3layer', (2) reading in the\
pattern file p.xor, (3) reading 'n.plot' with 'network + n.plot', and\
finally (4) computing an error surface with, for example,\
'exec sweep(InputHidden[0][0],HiddenOutput[0][1])'."

TRY errSurface
errSurface:

MSG "	For more information on how the plots are created, look at the\
procedure definitions in 'net/n.plot' and also do 'help plot' and\
'help plotlist'."

MSG "	The next section shows how to print out values in the network."

WAIT
CheckNet Section11
Section11:
StartSection 11 Printing Network States - 'print' and 'printlist'

MSG "	The graphic displays explained so far help you to see\
patterns in a large set of values like a vector or a weight\
matrix.  If you want to know these values more precisely,\
you can use the commands 'print and 'printlist', which are\
analogous to 'display' and 'dlist' but are used to print\
numbers instead of graphic displays.  For example:"

SHOW print Hidden

MSG  "Like 'display' you can give any layer name, including \
various components of a layer, a connection name, or any expression\
as the first argument to 'print'.  Compare, for example, 'print\
HiddenOutput**T(Hidden)' and 'print Output:net'"

TRY print
print:

MSG "	'Print' takes two optional flags for specifying the\
format of printing.  For example:"

SHOW print Output c2 p10

MSG "	The flag 'c2' is a shorthand for 'column2' and as\
for the command 'display', it specifies the number of\
columns for the printout, that is, the number of values to be \
printed on each row.  The flag 'p10', which is a shorthand for\
'precision10', specifies\
the precision for printing.  Try printing different items\
with these flags."

TRY printFlag
printFlag:

MSG "	The command 'printlist' works exactly analogous to how 'dlist'\
works for 'display'.\
It takes the same arguments as 'print' and adds an item to the 'print list'.\
For example:"

SHOW printlist target-Output c-1

MSG "	'c-1' has the special meaning that it should print no \
new-line character at the end of line."
MSG "	The items in the print list can be printed (1)\
simply by typing 'print'; (2) after each pattern\
presentation in the command 'present'; or (3) after every N\
cycles while running 'cycle' where N is the value of the\
parameter 'print' (default=1).  Try 'print', 'present all'\
and 'cycle 10', etc.."

TRY printlist
printlist:

MSG "	You have learned various ways to display the states of the\
network.  However, it could be a lot of work to manually set up the\
graph, the display list, and the command list every time you read in a\
network file.  Especially, when you are testing a network, you are\
likely to run it over and over again.  One solution is to make a file\
in which you put a set of commands necessary to set up a nice display\
you have worked out and 'source' that file every time you read in the\
network file.  ('source' is a built-in shell command).  This will not\
work, however, for interactive commands such as 'window' and 'graph'.\
The next section is about a command that solves this problem\
nicely. "

WAIT
CheckNet Section12
Section12:
StartSection 12 Screen Specification File - 'screen'

MSG "	The command 'screen' reads in a file with special format that\
allows you to open windows, open graph, setup display list, and even\
draw simple pictures.  In case we have any plotting on the screen:"

SHOW plot erase all

MSG "	and read in a screen file for our three-layer network."

SHOW screen scr.3layer -f

MSG "	What you see on the screen now is a picture of the network on\
the left, the two weight matrices in the center, and the response of\
the layers (from the bottom) Input, Hidden and Output to the four\
patterns.  Near the top-right-hand corner is the graph.  As before, the\
display of the weights are done with the display list, and the display\
of the responses are done with the command 'response' put into the\
command list.  You can check these by typing 'dlist' and 'clist'.  Try\
running some cycles (reset the network if necessary) and see what the\
display does."

TRY screen
screen:

MSG " It is beyond the scope of this on-line tutorial to explain about\
the format of the screen file, but if you are interested you can look\
at the file scr/scr.3layer which is designed to work for any three \
layer network.  It first opens the windows, draw the picture of the \
network out of circles and lines, opens a graph, and finally executes\
commands for setting up the display list and the command list (which\
we already know about)."

MSG "	The last section of this tutorial explains how to\
save the state of a network into a file so that you can\
later construct an identical network and continue running\
and examining it."

WAIT
CheckNet Section13
Section13:
StartSection 13 Saving Network States - 'savefile' and 'save'

MSG "	 You can save the values of the connection weights \
of a network in a file.  The command 'savefile <file name>'\
opens a file for subsequently saving the weights.  The\
parameter 'save' specifies how frequently the weights\
should be saved: if save is set to N (>0), weights will be\
saved at every N cycles (no saving if N=0, which is the\
default). The command 'savefile close' closes the current\
file."

MSG "	Let's try saving weights in a file.  Set 'save' to\
100, for example.  Reset the network (network reset) and\
type 'savefile <filename>' (name your file).  If \
the current directory $cwd is not your own, use your own directory or\
/tmp, for example.  (e.g., 'savefile /tmp/wts.a')\
Type 'graph clear' to initialize the graph and run the network\
with, say, 'cycle 300'."

TRY save
save:

MSG "	The error and the weights now have been saved several\
times.  The weights can also be saved at any time simply by typing\
'save'.  Close the file by 'savefile close'."

MSG "	It is also possible to save a vector by the command\
'save <vector>'."

MSG "	A file created by 'savefile <file name>' can be\
retrieved by the command 'read <file name>'.  Try reading\
the file you just saved the weights in.  Each file actually\
contains the information about what network file and\
pattern file were being used, and the network and the\
patterns are set up automatically when the file is read."

TRY read
read:

MSG "	'Read <file name>' reads in the \
first set of weights saved in the file.  Use the command\
step to read in the next error or a set of weights, or step\
N to read in the error/weights saved at step N.  Type 'step\
300' and, if the weights have been saved properly, the\
state of the network will be exactly the same as when you\
closed the save file."

TRY step
step:

MSG "	We have now come to the end of this tutorial. I hope\
it has helped you to understand the basic structure of\
$PROG interface and that you feel confident enough to go\
on on your own.  Would you like to experiment with the \
commands you have learned or go back to some section?"

TRY again
again:

goto END

TryOut:

if( $?LogIt ) $SAY try $RETURN >> $LogFile

while( 1 )
  SAYN "n(ext) s(ection) a(gain) e(nd) ?: "
  set INPUT = $< 
  if( $?LogIt ) $SAY "	$INPUT" >> $LogFile
  switch( "$INPUT" )
    case n:
    case next:
	if( $?LogIt ) $SAY end $RETURN >> $LogFile
	set PREVIOUS = $RETURN
	goto $RETURN
    case a:
    case again:
	goto $PREVIOUS
    case s:
    case section:
	goto Menu
    case e:
    case end:
	goto END
    case '?':
     $SAY "* Type any $PROG command."
     $SAY "* 'n(ext)' to proceed to the next instruction."
     $SAY "* 's(ection)' to see the table of sections and go to a different section."
     $SAY "* 'a(gain)' to repeat instruction."
     $SAY "* 'e(nd)' to end this tutorial."
     $SAY "* '?' to get this information."
     breaksw
    case help*:
    case set*:
    case nset*:
     $COM "$INPUT" | MORE
     breaksw
    default:
     $COM "$INPUT"
  endsw
end

SetupNetwork:
$COM cd $cwd
$COM network > /dev/null
if( $status == 0 ) goto SetupPattern
if( ! -f net/$NetFile ) then
  ERR "the network file net/$NetFile is missing in this\
example directory."
endif
MSG "	Hit RETURN to set up the network."
SHOW network $NetFile
if( $status ) then
  ERR "there was an error in the network file net/$NetFile"
endif

SetupPattern:
$COM pattern > /dev/null
if( $status == 0 ) goto $GOTO
if( ! -f pat/$PatFile ) then
  ERR "the pattern file pat/$PatFile is missing in this\
example directory."
endif
MSG "	Hit RETURN to set up the pattern."
SHOW pattern $PatFile
if( $status ) then
  ERR "there was an error in the pattern file pat/$PatFile."
endif

goto $GOTO

HandleError:
MSG "	Sorry," $ErrMsg
if( $?INSTALLER & ${INSTALLER}null != null ) then
  MSG "	Notifying $INSTALLER... $INSTALLER will let you know when\
the problem is fixed."
  MSG "$ErrMsg for user $USER on machine $HOST" | $MAIL $INSTALLER
endif
exit

END:

Quit:
$SAY "Quit $PROG with 'quit'."
SHOW quit
## if( $?WinSize_Orig ) then
##    changeWinSize $WinSize_Orig[1] $WinSize_Orig[2]
## endif

MSG "	You can always come back to this tutorial and choose\
specific sections that you wish to\
review.  You can also read the User's Guide which has more complete\
description of the commands we have seen plus some commands that are\
not included in this on-line version.  It also discusses the\
$PROG language used in network specification files.  The\
Reference Manual always provides complete\
descriptions of both the interface commands and the\
language."

if( $?LogIt ) then
  $SAY "End: " `/bin/date` >> $LogFile
else
  goto Comments
endif

SAYN "\
Can I send the log of this session to $AUTHOR? [y/n]: "
set INPUT = $<
if( $INPUT =~ y* ) then
  $SAY "Thank you."
  $MAIL -s "Log of $USER" $AUTHOR < $LogFile
endif
/bin/rm $LogFile

Comments:

$SAY "\
Your comments about this tutorial would be greatedly appreciated."

SAYN "Would you care to send a comment to $AUTHOR? [y/n]: "
set INPUT = $<
if( $INPUT =~ y* ) then
  $SAY "Thank you.  Invoking mail...\
Type your comment, ending with ^D."
  $MAIL  -s "comment from $USER" $AUTHOR
endif

$SAY "\
If you are ready to try $PROG on your own, follow these steps."
MSG "	(1) Type 'source $DIR/RunNet'."
MSG "	(2) Type in any $PROG commands."

$SAY "Bye bye"
