This is the README file from the elastic simulator - a generative model
simulator that has been used for handwritten digit recognition. (See the paper
Using generative models for handwritten digit recognition, Revow, Williams and
Hinton.) The simulator and papers are available from
http://www.cs.toronto.edu/~revow

What you need to build this simulator.
--------------------------------------

The software will only run under UNIX. I have successfully compiled it under
IRIX 5.* and SunOS 5.4. I do not know what happens under other flavours of
UNIX. The following additional software is also needed:

1) The Xerion neural network simulator libraries, Version 3.1 (Available from
ftp.cs.toronto.edu pub/xerion/3.1)

2) The following files from Numerical Recipes in C, Press, W.H, Flannery, B.P,
Teukolsky, S.A. and Vetterling, W. T. I used the ones that come with the first
edition of the book (1988).

jacobi.c
nrutil.c
ludcmp.c
lubksb.c
svdcmp.c


To Compile the simulator:
-------------------------

Untar the tar file. The Makefile is rather complicated as it was automatically
generated from IMAKE. You should only need to change line 30 which specifies
where you installed the xerion libraries.  Do a make depend, followed by by a
make elastic. I have only compiled the source under IRIX 5.* (sgi machines)




Running the simulator

When the simulator is started you enetr the command line loop. This is the
standard xerion shell (see xerion documentation). You run the simulator by
typing in commands. Type "help" at the command line to get a list of available
commands (There are many). To get more specific help on say the get-image
command type:

elastic-> help get-image
NAME
    get-image - Reads an image file

USAGE
    get-image [g]

DESCRIPTION
    An image is read by opening a pipe to another process
    which is expected to put a pgm formatted image on its stdout
    By default, the shell script read_digit_image is run
    Options:
    g - Preserve the grey scale levels in the image





To make thinsg easier, the simulator can read commands from script files. To
help you get running a few have been supplied. So I recommend that once you
start the simulator type:

elastic-> read init

To set up 10 models and set all parameters.

I have supplied a demo image (in file demo_image). This is an image of the
digit "2". You can fit varies models to this image by typing:

elastic-> u 2
elastic-> fit
elastic-> show np.lp
               np.lp = -241.669
elastic-> show np.model-energy
     np.model-energy = -18.4432

elastic-> u 8
elastic-> fit
elastic-> show np.lp          
               np.lp = -166.84
elastic-> show np.model-energy
     np.model-energy = 4.87879


Here we first fitted the 2 model to the image and showed the log-probability
and deformation energy of the fit. Then we fitted the model of an 8 and shoed
its log-probability and deformation image. Luckily the image is much more
likely under the 2-model!

There is much more that you can do if you play around with the simulator

Good Luck
Michael Revow (revow@cs.toronto.edu)