Jim Susinno 2003
Neural networks tutorial
v0.0.0
Mon Apr 21 13:18:06 CST 2003


This file will describe the usage of the glut/OpenGL executable 'glneuralnet' in detail.



-------------------------------------
COMMAND DESCRIPTION:

The program can be invoked as follows:
  Windows: drag the file 'animal1.net' onto the 'glneural' executable.
  *nix: ./glneural animal1.net

Upon execution, a glut window will appear with a colored 3d representation of the neural network loaded from file.
To begin learning associations, type the 'j' key.
  The 'jkl' keys control the learning process:
    j: sets network to learn continuously(IDLEfunc)
    k: stops the continuous learning
    l: perfoerm one step of the learning algorithm
  The number keys 1-5 seed the matrix with a set of initial values:
    1: random values from 0 to 1
    2: sequential values
    3: identity matrix
    4: all ones
    5: all zeros
  The mouse left button moves the on-screen text.
  The mouse middle button adjusts viewer height
  The mouse right button can be used to navigate space in 3d.
  The 'zxc' buttons can be used in cinjunction with the mouse to set the navigation mode in 3d:
    z: glide in the x-z horizontal plane
    x: change height in y-vertical direction(same as middle button)
    c: look-at: change the viewing direction without changing viewpoint location




-------------------------------------
SAMPLE INSTRUCTIONS:

So, if youd like to try a sample learning run, do the following:
 - invoke glneuralnet with animal4.net as a parameter
 - type '1' to seed the amtrix randomly
 - type 'j' to start the auto-learn(IDLE) function
 - watch the error graph:
    if it converges to 0.0, the pattern is learned.
    if it does not converge to 0.0, the network has not correctly learned the pattern.




-----------------------------------
FILE FORMAT DESCRIPTION:

If you would like to test out a custom set of input-output pairs, you can write you own ".net" text file.
Below is the entirety of the file "animal1.net":

4 4
hoof
gills
feathers
bill
horse
fish
bird
platypus
1 0 0 0 = 1 0 0 0
0 1 0 0 = 0 1 0 0
0 0 1 0 = 0 0 1 0
0 0 0 1 = 0 0 0 1


(EOF "animal1.net")

The first line always consists of 2 integers; these are the dimensions of the input-output matrix.
The first number is the number of inputs to the system, in this particular example, the set 
    {hoof, gills, feathers, bill}.
These attributes are represented by bits, or an integer of {0,1} value.
The bit represents an on/off flag for the attribute in question.
For example, the bit string 0100 corresponds to a 0 for hoof, 1 for gills, 0 for feathers and 0 for bill.
    This list of attributes represents some abstract notion of an animal that has gills, but no feathers bill or hooves.

The second number is the number of outputs, in this case:
    {horse, fish, bird, platypus}
The bitfield works in exactly the same way as the input, denoting an animal that is a horse or a fish, etc.
There is a notable difference however, in the fact that an output may have only ONE value set to 1 in any of its bitfields.
To do otherwise would be to introduce a contradiction into this simple system.