--------------------------------------------------------------------------------
                                 EUREKA README file

   Copyright (c) 1998, D. J. Cook and R. C. Varnell, The University of Texas
at Arlington.  This program may be freely copied, used, or modified provided
that this copyright notice is included in each copy of the code and parts
thereof.

   THIS SOURCE CODE IS SUPPLIED  "AS IS" WITHOUT WARRANTY OF ANY KIND, AND ITS
AUTHOR AND THE JOURNAL OF ARTIFICIAL INTELLIGENCE RESEARCH (JAIR) AND JAIR'S
PUBLISHERS AND DISTRIBUTORS, DISCLAIM ANY AND ALL WARRANTIES, INCLUDING BUT NOT
LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE, AND ANY WARRANTIES OR NON INFRINGEMENT.  THE USER ASSUMES
ALL LIABILITY AND RESPONSIBILITY FOR USE OF THIS SOURCE CODE, AND NEITHER THE
AUTHOR NOR JAIR, NOR JAIR'S PUBLISHERS AND DISTRIBUTORS, WILL BE LIABLE FOR 
DAMAGES OF ANY KIND RESULTING FROM ITS USE.  Without limiting the generality of
the foregoing, neither the author, nor JAIR, nor JAIR's publishers and
distributors, warrant that the Source Code will be error-free, will operate
without interruption, or will meet the needs of the user.
--------------------------------------------------------------------------------


   EUREKA is a parallel search engine that combines a number of search
techniques including:

   * distribution techniques
     (parallel window search, distributed tree search, Kumar & Rao search,
      clustering)

   * ordering techniques
     (operator ordering - TOIDA, local ordering, no ordering)

   * load balancing techniques
     (load balance on or off, percent giveaway, anticipatory load balancing,
      nearest neighbor or random neighbor)

  To run this program, you need to create a job file (see sample.job for an
example).  The job file specifies where the problem is stored, where the
output file should be located, where the executable is located, and the system
parameters.  The system parameters are specified as environment variables
and include the following:

   numnodes:     number of processors to work on this job
   distribtype:  KUMAR or DTS
   numclusters:  power of 2 in the ranger [1..numnodes]
   alpha:        floating point value in [0.0..1.0] representing percent of
                 stack given away during load balancing
   anticipatory: integer value indicating number of nodes remaining in open
                 list that triggers work request
   giveaway:     TOP or BOTTOM, donate work from front or end of open list
   optimal:      OPTIMAL or SUBOPTIMAL, search for optimal or first solution
   loadbal:      NEIGHBOR, RANDOM, or OFF, request work from a processor that
                 is one hop away, from any randomly-chosen processor, or use
                 no load balancing
   threshold:    -1 (threshold set to h(root)) or integer value
		 Integer value should be obtained from information about the
		 search space, can obtain from shallow search of tree
   ordering:     LOCAL, TOIDA, or NONE
   order:        initial operator evaluation order
   datafile:     file where puzzle initial state is stored
   log:          output file
   consultdir:   directory where C4.5 data and rules are stored, this parameter
                 must be defined before distribtype, alpha, anticipatory,
                 giveaway, loadbal, ordering, or numclusters

   Several of the system parameters can be automatically set by EUREKA rather
than manually set.  In particular, the parameters distribtype, loadbal,
ordering, alpha, giveaway, numclusters, and anticipatory can be automatically
set by defining the parameter value as CDISTRIB, CLOADBAL, CORDER, CALPHA,
CGIVEAWAY, CNUMCLUSTERS, or CANTICIP, respectively.  EUREKA will look in the
directory specified by "consultdir"for the file "distrib.rules",
"loadbal.rules", "ordering.rules", "alpha.rules", "giveaway.rules",
"clusters.rules", or "anticip.rules", and will use the information stored in
this file to make a strategy selection.

   To make a strategy decision, EUREKA performs a shallow search to measure
features of the search space.  In particular, EUREKA searches using IDA* until
the number of generated nodes is greater than or equal to SAMPLESIZE, then
consults the C4.5-generated rules file to set the parameter value.  The files
in the c4.5/data directory contain sample data that can be used to select
1, 2, or 4 clusters.  The attributes used to describe training examples in
this directory are the problem number (ignored by C4.5), the average branching
factor, the heuristic error, tree imbalance, and the heuristic branching factor.


Installation:

   In order to install this program you will need to have a working version of
the Parallel Virtual Machine (PVM) software installed.  The PVM source code can
be downloaded from http://www.epm.ornl.gov/pvm/pvm_home.html.

   The EUREKA program makes use of some modified functions from the C4.5
system (http://www.mkp.com/books_catalog/1-55860-238-0.asp).  This code,
written by Ross Quinlan, is copyrighted software and is not in the public
domain.  In particular, files consultr.c, getnames.c, rules.c, trees.c,
userint.c, and defns.i contained code modified from the original C4.5
distribution.  Our code only consults the learned C4.5 rules to make strategy
decisions for a new search problem.  To generate the decision tree or learned
rules, or to make further improvements of this type to the EUREKA system, you
will need to obtain the C4.5 source code.

   To compile and install the EUREKA system, you will need to edit the PVM_ARCH
and BDIR variables in the Makefile and then type "make".

   Send mail with comments and suggestions to Diane Cook (cook@cse.uta.edu) or
Craig Varnell (varnell@cs.sfasu.edu).
