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

I. Solving A Single Existing Zebra or Sherlock Problem

   All the bcsp (binary constraint satisfaction problem) solvers have the same
   usage rules.  The format is:

	solver [-q [solution-file]] problem-file

	Where solver is one of: Arc, BM_CBJ2, BM_CBJ2_NoArc, DoubleX, GT, GT10k,
	Mutate, or Xover and is located in the bin directory; 

	problem-file is the bcsp to be solved (in the format outlined in 
	the 'CSP-file-format' file in this directory);

	-q (optional) indicates quiet mode (only display numerical results 
	(number of constraint checks performed, and possibly nodes or tested 
	solutions))

	and (optional) solution-file is the file in which to save the solution 
	found by the solver.

	EXAMPLES:

	In input directory:

		../bin/BM_CBJ2 z-classic-zebra.csp

		Outputs:

		File is a Zebra problem.
		Performing constraint propagation
		Finished constraint propagation, starting search
		Y B R I G 
		K C O L P 
		N U E S J 
		F H S D Z 
		W T M O C 

		24974 checks, 831 nodes.
		0 unique nodes.

	A) Algorithms Used By Solver

		Arc		AC-3	(Achieve arc-consistency)
		BM_CBJ2		BM-CBJ2 (Backmarking with Conflict-directed
		   		Backjumping 2 and AC-3 preprocessing)
		BM_CBJ2_NoArc	BM-CBJ2 without AC-3 preprocessing
		DoubleX		DoubleX genetic algorithm
		Mutate		Mutate genetic algorithm
		Xover		Xover genetic algorithm				

II. Generating a Single Zebra or Sherlock Problem

	All the bcsp generators have the same usage rules.  The format is

	generator S|Z output-filename solution-filename

	Where generator is one of GenStrongKProblem or GenTotalRand,

	S|Z is one of S (for Sherlock) or Z (for Zebra),

	output-filename is the file in which to store the created problem,

	and solution-filename is the file in which to store the solution for
	the created problem (not optional).

	A) Algorithms Used by Generator

	GenStrongKProblem	Until AC-3 can solve problem, generate random 
                                clues which have one already known variable and 
				one new variable.  Should there be no valid 
				clues which meet this criteria try both unknown,
				then both known.

	GenTotalRand		Until CBJ-Multi detects only one solution, 
				choose a random clue from the set of all valid 
				clues.


III. Generating a Set of Problems

	The following commands generate bcsp problem files in the input/type 
	directory and solutions in output/solutions/type directory (where type 
	is strongK or totalRand).

	create-z-k-case    Generates strongly k-consistent Zebra problems
	create-s-k-cases   Generates strongly k-consistent Sherlock problems
	create-z-tr-cases  Generates 'totally random' Zebra problems
	create-s-tr-cases  Generates 'totally random' Sherlock problems

	These commands must be executed while in the bin directory.
	Each command takes an optional start and end parameter 
	(e.g. create-s-k-cases 5 10 generates strong k-consistent Sherlock 
	problems numbered from 5 to 10).

IV. Solving a Set of Problems

	solve-cases solver s|z k|tr [start [end]]

	Solves problems numbered starting at start (or 1 of no start) and ending
	at end (or 1000 if no end) using the solver (as above) specified.

	s or k for Sherlock or Zebra must be specified along with
	k or tr for strongly k-consistent or 'totally random'

	This script assumes that the problems to be solved can be found in
	input/type, the solutions in output/solutions/type, and that the 
	directory output/results/type exists and can be used to store the 
	results.

	This script also collects the data in a spreadsheet-friendly format and 
	stores it in output/results/type1type2-solver.csv 
	(e.g. ZebratotalRand-Mutate.csv)

