What is DISCERN?
================

This directory contains the code and data for running the complete,
trained DISCERN system. See 
@Book{miikkulainen:subsymbolic,
  author = 	"Risto Miikkulainen",
  title = 	"Subsymbolic Natural Language Processing: {A}n
		 Integrated Model of Scripts, Lexicon, and Memory",
  publisher = 	"MIT Press",
  year = 	"1993",
  address = 	MIT-ADDR
}
for details. A short summary paper is available by anonymous ftp at
cs.utexas.edu:pub/neural-nets/papers/integrated.ps.Z.

How do I run DISCERN?
=====================

First copy the contents of the file Discern in your .Xdefaults file, or
copy the file in your app-defaults directory.  Change the CC, CFLAGS,
INCLUDES and LPATHS variables in the makefile as necessary in your
system. Compile with "make".  Then run DISCERN with "discern". 

DISCERN will read system specs from the file "init", loading up the
various weight files and setting default values for various parameters.
A graphics window will come up with a number of buttons (described
below).  Click on "Run" to start simulation: the graphics display shows
activity propagation through the networks, and detailed log output is
generated in the standard output.  You can stop and continue the
simulation at any time, read and simulate new input files, print
performance statistics, and change various system parameters through the
command interface.


X Display
=========

"Run": click here and DISCERN will start a simulation run, reading input
from the default input file. While the simulation is running, the "Run"
button changes into a "Stop" button:

"Stop" button; you can interrupt the run at any time by clicking on it,
and it changes into the "Run" button. Click "Run" again and the
simulation continues.

"Step" is a toggle switch; when on, it causes DISCERN to pause after
every major propagation in the network. Click "Run" to continue.

"Clear" interrupts the currently running simulation and clears the
networks.

"Quit" terminates the program.

The area right of the "Step" button is a command window (see list of
commands below). It comes up with "file input" as the default command
(indicating that the name of the default input file is "input").
Anything you type into the DISCERN display will go to the command
window. You can edit the text with standard emacs-style commands.
Hitting "Return" will send the command to DISCERN (if you have installed
.Xdefaults properly).

The display interacts with the window manager in the normal manner. You
can iconize it, resize it (unfortunately the fonts are not resizable
though), change default parameters in the app-defaults or .Xdefaults
file, etc.



Commands
========

DISCERN reads commands from the command window on the X display (or if
the display is off, from the terminal I/O interface), or from an
inputfile.  The commands are (with variable info inside <>):

Various things to do:
--------------------

"file <filename>"
Read commands from the file "filename".

"text-question <words separated by blanks>"
You can type in a question such as "Who ate lobster at Leone's ?", and
DISCERN will process it. The question is not sensitive to case. The
number of words exceeding the nwords parameter will be ignored. Remember
to separate the "?" from the previous word with a space.

"list-params"
Lists the current weight and input file names and various parameters.

"init-stats"
Initializes the statistics collecting system.

"print-stats"
Prints out performance statistics collected since the last "init-stats".

"clear-networks"
Clears the networks (but does not interrupt a possibly ongoing simulation).

"displaying <1/0>"
"displaying 1" turns the X display on; "displaying 0" turns it off.

"quit"
Terminates the program.

"stop"
(meaningful only in an input file) Causes the simulation to stop. Click
"Run" (or hit return if the display is not on) to continue.

"echo <text>"
(inputfile) Prints <text> in the log output.

"#<text"
(inputfile) The entire line is treated as a comment (ignored).

"read"
(inputfile) Tells DISCERN to read a story given in the next nsent+1
input lines.  This command is ignored if given in the command window
(but not in the terminal I/O interface so that you can input a file
through the standard input if you wish; see the file input-test-all).

"read-and-paraphrase"
(inputfile) Tells DISCERN to read and paraphrase a story given in the
next nsent+1 input lines. Ignored in the command window.

"question"
(inputfile) Tells DISCERN to process the question specified in the next
3 input lines. Ignored in the command window.


Various simulation parameters
-----------------------------

"displaying <1/0>"
"displaying 1" turns the X display on; "displaying 0" turns it off.

"chained <1/0>"
When on, the output of one module is fed to the input of the next. When
off, clean and correct representations (taken from the lreps and sreps
file) are used instead.

"withhfm <1/0>"
Whether to include the episodic memory in the simulation runs or use the
output of the story parser directly as input to story generator and
answer producer.

"withlex <1/0>"
Whether to include the lexicon in the simulation runs or use semantic
representation directly as I/O.

"babbling <1/0>"
When on, detailed log output will be printed in the standard output.

"print_mistakes <1/0>"
When on, erroneus words (together with the correct word) will
be printed in the standard output even when babbling is off.

"log_lexicon <1/0>"
When on, the propagation in the lexicon (lexical <-> semantic
representations) will be logged in the standard output (if babbling is
on). It is easier to read the output if log_lexicon is off.

"ignore_stops <1/0>"
Do not stop when "stop" command is encountered (useful for collecting
statistics).

"hfmsearch <float>"
The search threshold for script level of the episodic memory.

"subsearch <float>"
The search threshold for track level of the episodic memory.

"withinerr <float>"
Statistics collected within e.g. 0.15 of the correct value.


Configuration Files
-------------------
The weight files should not really be changed on the fly unless you
really know what you are doing.

"lvocfile <filename>"
Lexical word labels are read from this file.

"svocfile <filename>"
Semantic word labels.

"lrepfile <filename>"
Lexical representation vectors.

"srepfile <filename>"
Semantic representation vectors.

"qafile <filename>"
FGREP module weights.

"hfmfile <filename>"
Hierarchical feature map weights.

"hfminpfile <filename>"
Labels for the cells in the hierarchical feature maps.

"lexfile <filename>"
Weights for the lexicon module.


Configuration Parameters
------------------------
Should only be changed when the new configuration files so require.

"nslot <positive integer>"
Number of slots in the script representation.

"ncase <positive integer>"
Number of slots in the case role representation.

"nword <positive integer>"
Max. number of words in a sentence.

"nsent <positive integer>"
Max. number of sentences in a story.


Trace feature map parameters
----------------------------

"tracenc <nonnegative integer>"
Radius of the stored trace.

"tsettle <positive integer>"
How many settling iterations in memory retrieval.

"epsilon <positive float>"
If activity of trace map unit A is epsilon larger than B, a positive
connection from B to A is formed.

"aliveact <positive float>"
If the response is oscillating and the lower value is less than
aliveact, consider it a failed retrieval.

"minact <float>"
Lower threshold of the piecewise linear sigmoid approximation.

"maxact <float>"
Upper threshold of the piecewise linear sigmoid approximation.

"gammaexc <positive float>"
Magnitude of the excitatory lateral weight in the trace map (\gamma_E).

"gammainh <negative float>"
Magnitude of the inhibitory lateral weight in the trace map (\gamma_I).



How to change the defaults
==========================

If you don't like the default fonts, colors, filenames, window sizes
etc., you can change them in the .Xdefaults file. If you want to change
the default parameters, edit the file "init", or prepare another
initfile and give that as a parameter to DISCERN ("discern
my-init-file").


Inputfiles
==========

The file "input-example" contains the example run discussed in detail in
Chapter 11 of "Subsymbolic Natural Language Processing".

The file "input-all-complete" is a collection of all stories where every
sentence has been included in the input. "input-all-incomplete" has the
same stories but only three sentences per story.


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

Copyright (C) 1990 - 1993 Risto Miikkulainen

This software can be copied and distributed freely for educational and
research purposes, provided that the source is acknowledged in any
materials and reports that result from its use. It may not be used for
commercial purposes.

I would appreciate if you would let me know of any attempts to use this
software. You can send questions, comments, bug reports and suggestions
to risto@cs.utexas.edu. However, the software is provided as is, and I
am under no obligation to maintain it. You should know that this is
software that I have used in my research, and I have not made a great
effort to clean it up for public use.
