============================================================================

		Perceptual Grouping LISSOM - a Brief Manual

============================================================================

Program:	PGLISSOM v1.3 (derived from SLISSOM v1.0)
Date:		$Date: 2004/06/03 23:46:42 $
Author: 	Yoonsuck Choe <choe@tamu.edu>
Copyright: 	All code, documentation and examples follow the
		GNU Public License (http://www.gnu.org).
		The grafix package, used in slissom, written by 
		Wolfgang Koehler and improved by Y Choe. 
		is also distributed under GPL.

		Some code in the tools/ directory are also by the 
		authors indicated as follows:

		cart2pol.m:## Copyright (C) 2000  Kai Habel
		gradient.m:## Copyright (C) 2000  Kai Habel
		ifftshift.m:## Copyright (C) 1997 by Vincent Cautaerts
		pol2cart.m:## Copyright (C) 2000  Kai Habel
	
		These are also originally released under GPL. Certain
		modifications by Yoonsuck Choe may have been incorporated
		into the original code.

Disclaimer: 	Program still under development. No warranty.

Distribution: 	http://faculty.cs.tamu.edu/choe/src/

			----------------------
			   Table of Contents
			----------------------

		*. Requirements
		I. Building
		II. Testing
		III. Simultation Configuration File 
	 	     and Commandline interface.
  		IV. Release Note

		Acknowledgements: This research was supported in part 
		by National Science Foundation under grant #IRI-9811478, 
		in part by Schlumberger Graduate Fellowship, and 
		by National Institute of Mental Health under grant 
		#1R01-MH66991.

		* This program is a part of the Topographica
		   simulation environment: http://www.topographica.org.

============================================================================

*. Requirements

============================================================================

	GNU compiler tools : gcc, g++, make, makedepend 
	grafix-1.4 	: a GUI library written in C++ -- 
			  included in  ./grafix-1.4y3
	GNU readline	: text interface library -- ftp://ftp.gnu.org/
	Perl	   	: at least version 5 -- http://www.perl.org
	GNU bash   	: Bourne Again SHell 
	xv		: graphics viewer -- http://www.trilon.com/xv/

	octave		: optional -- for extra visualization

============================================================================

I. Building

============================================================================

	Suppose you have set up a directory called srcdirectory
	where you want to untar the whole stuff.

	ungzip and untar pglissom-1.1.tar.gz

		cd srcdirectory
		gzip -dc pglissom-1.1.tar.gz | tar -xvf - 

	cd into srcdirectory/pglissom

		cd srcdirectory/pglissom

	edit the Makerules file. Especially be aware of the
	various include and library directories and OS specific
	libraries (like -lnsl -lsocket for SunOS), and also the
	installation target directories (LIB_TARGET and BIN_TARGET).

	Create directories by running

		make dirhier

	and then run the following command to build and install everything:	

		make

	This will

		1. build and install the library libnnview.a in 
	
			$LIB_TARGET/lib/

		2. install the headers in 

			$LIB_TARGET/include/nnview/

		3. build slissom2-2 in 

			srcdirectory/pglissom/test/

		4. build tools in

			srcdirectory/pglissom/tools/

		5. install slissom2-2 and tool binaries in

			$BIN_TARGET/
			
	Now, finally, add ~/bin/ to your PATH environment variable:

		csh, tcsh:

			setenv PATH $PATH:$HOME/bin

		sh, bash:

			PATH=$PATH:$HOME/bin; export PATH

	* Note that there is a problem compiling under
	  the 64bit Sun architecture. This issue is being addressed
	  at the moment.

============================================================================

II. Testing

============================================================================

2.1 Standard examples

	Go into srcdirectory/pglissom/test/demo/

	Now run

		script demo-4seperate.out
		../slissom2-2 demo-4seperate.conf 

	When the GUI window comes up, click on the [Test] button.

	Once the simulation is done, click on the [Quit] button to 
	exit.

	Exit from the script and run the spike display program

		procspikes demo-4seperate.out

	and the Multi Unit Activity program

		procppmmua 4 demo-4seperate.out

	Notice that "procppmmua" requires one extra argument "4" indicating
	the number of activity areas. Also, slissom2-2 is actually 
	two maps, but only map1 is used in the simulation, so you can
	ignore the map2 output. 

	Both these scripts (procspikes, procppmmua) use 

		perl
		bash
		xv

	so you need to have it somewhere.

	Try out the other configuration: demo-3connected.conf .

2.2 Specific examples

	srcdirectory/pglissom/simulations/ contains configuration
	files to replicate results presented in the tech report:

@TechReport{choe:bc02,
  author        = "Yoonsuck Choe and Risto Miikkulainen",
  title         = "Contour Integration and Segmentation in a
                        Self-Organizing Map of Spiking Neurons",
  year          = 2002,
  institution   = TAMUCS,
  number        = "2002-1-2",
  note          = "15 pages",
  bibdate       = "Wed Jan  9 04:29:08 CST 2002",
  bibauthor     = "yschoe",
  annote        = "
        ",
}

	available at the URL:

	http://www.cs.tamu.edu/faculty/choe/ftp/publications/choe.tr02.1-2.pdf

============================================================================

III. Simultation Configuration File and Commandline interface.

============================================================================

	Now let me explain what the different parameters 
	in the simulation configuration file mean and how
	to set them.	

	See the CONFIG-HOWTO file from here on.	

============================================================================

IV. Release Note

============================================================================

	v1.2

	In this release, miscellaneous tools have been updated in the 

		srcdirectory/pglissom/tools/

	directory. Most of these are octave m-files, with specific
	instructions given as comments at the beginning of each file.
	Some files are from other sources, and the original source
	was cited as such.

	A major change for the pglissom simulator is the inclusion of
	curved inputs. These inputs are available during training and
	can be turned on by setting the hemifield_curvature_flag to 1.
	Two additional parameters are available, upper_hemifield_curvature
	and lower_hemifield_curvature to independently control the degree
	of curvature in the lower vs. the upper hemifield of the retina.
	Usual values are between 10 and 40.

	v1.3

	In this release, more tools have been added to the 

		srcdirectory/pglissom/tools/

	directory. The new tools are mostly for visualization of
	the various data files generated by pglissom.


Yoonsuck Choe