SIGNALSIM (Version 3.0)
=================


Running SIGNALSIM
===========

The system is run by typing "signalsim scripts/SCRIPTNAME.tcl" from the top
directory SignalSim/.  The script gives you the full power of TCL/TK, plus 
any widgets defined and compiled in the "signalsim" program itself.


Scripts (scripts/SCRIPTNAME.tcl)
================================

A number of scripts have been provided to illustrate how typical networks 
can be constructed which use the commands and widgets in the signalsim 
program.  Also included is a handy tool that allows an entire lexicon to 
be viewed.  These are:

net.tcl:        a sample annotated script that implements a very simple
                three-neuron network with some feedback connections.
and-simp.tcl:   a simple and gate (composed of three neurons)
xor-simp.tcl:   a simple xor gate (composed of five neurons)
xor00-rob.tcl:  a robust xor gate (five neurons with many connections)
xor01-rob.tcl:  a robust xor gate (five neurons with many connections)
xor10-rob.tcl:  a robust xor gate (five neurons with many connections)
xor11-rob.tcl:  a robust xor gate (five neurons with many connections)

-----------

We'll only go over the most basic components here, as the script can become
as complex as needed for the task.

The script will usually begin with a number of variables which will keep
track of the state of the network, plus other housekeeping functions
needed for the TK display.

A number of procedures follow which encapsulate some standard routines
(such as displaying the network activations and spike trains).  Auxiliary 
procedures for operations to be performed (such as resetting the network) 
are also included here.  An important procedure is Step, which specifies 
the actions to be taken by the network at each point in the simulation.

TK definitions for display purposes are given later.  Typically, we'd
want a menubar to handle standard functions for running, stepping through,
clearing, and resetting the network.

Network topology is specified at the end of the file.  This is where the
"Neuron" widget comes in--to represent the layers of the network
and links between them.

General Use
-----------

The Display(s):

Color Allocation:

The current implementation uses a rainbow color scheme to display unit
(or link) activations.  Typically, the units in a layer will range between
0.0 (black) and 1.0 (white).  Values within the range (0.0,1.0) have
been (arbitrarily) denoted by breaking the color wheel from dark blue
(< 0.1) to bright magenta (> 0.9).  According to the formula used to
determine the RGB values, the value 0.5 works out to be green.  The exact
colors that will appear on the screen will depend on the number of color
cells allocated.  The color translation routine will also accept units 
within the range [-1.0,1.0] and [-inf,inf], scaling them accordingly.  In 
the upgrade, this will be placed on more solid theoretical footing to ensure 
that color allocation is more evenly distributed.


The Menubar:
------------
1.  "Run" will run through the network until pressed again or until
    the epoch number matches the end_epoch parameter.
2.  "Step" will step through the network one word at a time.  Because
    this is a shift-reduce task, the input word may occur more than
    one time to allow for reductions to be made.
3.  "Clear" will clear the appropriate network back to the beginning of 
    the data set.
4.  "Reset" will reset the network to random weights.  This is
    usually only used for training.
5.  "Quit" will destroy the appropriate window.


Credits etc.
============

Copyright (C) 2002 Marshall R. Mayberry

This software can be copied, modified and distributed freely for
educational and research purposes, provided that this notice is included
in the code, and the author is acknowledged in any materials and reports
that result from its use. It may not be used for commercial purposes
without expressed permission from the author.

We hope that this software will be a useful starting point for your own
explorations in connectionist NLP. The software is provided as is,
however, we will do our best to maintain it and accommodate
suggestions. If you want to be notified of future releases of the
software or have questions, comments, bug reports or suggestions, send
email to martym@cs.utexas.edu.
