###############################################################################
#
# README for CIS*4750 Course Project
#
# Author: Daniel F. Dickinson <danielfdickinson@yahoo.ca>
#
# Copyright 2002-2003, University of Guelph, All Rights Reserved
#
###############################################################################

I. Quick Start
	
	1.  To create the software and project report type 'make' (without the
            quotes) in the directory containing this file.

	2.  All the commands are now located in the 'bin' subdirectory of the
	    current directory.  Usually typing ./command by itself (while in
	    the 'bin' directory) will display a basic usage message.

	3.  The documentation (except this file) is located in the 'docs'
	    subdirectory of the current directory.

II. File Manifest

i. Distribution root directory

	bin	This directory is not present in the distribution, but is 
		created by the 'make bin' command.  It contains all the
		scripts and wrappers for the software created for this project.
	docs/	This directory contains the documentation for the project
	input/	This directory contains constraint satisfaction problems
		in the format used by the project software
	obj/	This directory contains the Java .class files for the project.
		It is does no exist until 'make' or 'make all' is executed.
	output/	This directory contains the results of the test cases used
		in writing the report for this project.
	src/	The source code
	templates/ This directory contains templates for Zebra and Sherlock
		   uniquness constraints.
	Makefile   The makefile for the project.  Contains targets 'all', 'bin',
		   'docs', and 'clean'.  'make all' compiles the Java code, 
		   'make bin' creates the bin directory and links for easy 
		    access to commands, 'make docs' creates the project report 
		    from DocBook sources (in docs), while 'make clean' removes 
		    all temporary and binary files.
	README	    This file.

ii. bin directory

	Arc		Solve a binary constraint satisfaction problem 
			(bcsp) using AC-3.
	BM_CBJ2		Solve a bcsp using BM-CBJ2 with AC-3 preprocessing.
	BM_CBJ2_NoArc	Solve a bcsp using BM-CBJ2 with no AC-3 
			preprocessing
	create-s-k-case	Create a set of strongly K-consistent Sherlock
			problems using GenStrongKProblem
	create s-tr-cases  Create a set of 'totally random' Sherlock cases
			   using GenTotalRand
	create-z-k-cases   Create a set of strongly K-consistent Zebra.
			   problems using GenStrongKProblem.
	create-z-tr-cases  Create a set of 'totally random' Zebra cases using
			   GenTotalRand
	do_time.sh	Measure the CPU and system time for a given
			algorithm.
	DoubleX		Solve a bcsp using the DoubleX algorithm.
	GenStrongKProblem  Create a directed-random bcsp (Sherlock or Zebra)
			   which is strongly k-consistent.
	GenTotalRand	Create a 'totally random' bcsp.
	Mutate		Solve a bcsp using the Mutate algorithm.
	run-generate.sh	A script which is symbolically linked to such that
			when the symbolic link is issued as a command this
			script executes the java .class file with the same
			name as the symbolic link.  It is designed for use
			with the bcsp generating software.
	run-solver.sh	As run-generate.sh but for bcsp solving algorithms.
	solve-cases	Solves a specified type of bcsp using the specified
			algorithm.
	solve-special-cases	Solves the special cases in ./input
	test-gen.sh	Test bcsp generation algorithms
	Xover		Solve a bcsp using the Xover genetic algorithm.

iii. docs directory

	sgml/		The DocBook source for the report
	CSP-file-format	Describes the file format used by all the Zebra
			and Sherlock problem generating and solving
			software.
	Makefile	The makefile for generating the the report from
			DocBook sources.  The top of this file contains
			details on how to get the document type of your
			choice.

iv.	input directory
	
	solutions/	Solutions for special case problems in this
			directory.
	strongK/	Strongly K-consistent Sherlock and Zebra problems
			generated using GenStrongKProblem (through
			create-s-k-cases and create-z-k-cases).
	totalRand/	'Totally random' problems generated using
			GenTotalRand (through create-z-tr-cases and
			create-s-tr-cases).
	find-solutions	A script to generate the solution files for the
			special cases in this directory.
	s-notK.csp	A Sherlock Problem that is not strongly
			k-consistent.
	z-classic-zebra.csp	The benchmark Zebra problem
	z-multi.csp		A Zebra problem with multiple solutions.
	z-no-solution.csp	A Zebra problem with no solutions.
	z-over-specified.csp	A strongly k-consistent Zebra problem.

v. output directory
	
	results/	The times, number of constraint checks, solutions,
			etc found by each algorithm.
	solutions/	Solutions to the problems in the input directory.

v.a. output/results directory

	strongK/	The times, number of constraint checks, solutions,
			etc found by each algorithm for problems generated
			the GenStrongKProblem algorithm.
	totalRand/	The data (as above) for problems generated using
			the GenTotalRand algorithm.
	*.csv		The time, constraint checks, nodes visited,
			algorithm, strongK or not, etc in a spreadsheet-
			friendly format.
	Analysis.qpw	The times, constraint checks, etc in a Quattro Pro
			spreadsheet.

v.b. output/solutions directory

	strongK/	Solutions for problems generated using 
			GenStrongKProblem.
	totalRand/	Solutions for problems generated using
	
vi.	src directory

	*.java		Java Source Code
	create-*-cases	Create the specified type of binary constraint
			satisfaction problem.  Installed in bin directory.
	*.sh		Scripts to be installed in the bin directory
			See description under bin directory for their
			purpose.
							

vii. templates directory
	
	sherlock-unique	The set of constraints which specifies that each
			row contains exactly one of each type of object
			(e.g. that the first row contains only one yellow
			house) for the Sherlock problem.
	zebra-unique	As sherlock-unique but for the Zebra problem.

