Directory Contents
==================

This directory contains the same basic programs as the main CSP directory
however the program has been specialized to simply solve graph-coloring
problems instead of general constraint satisfiability problems.  This has been
done by simply replacing the zero-one matrix along each edge by a simple
integer which represents whether the edge is an I (identity edge), a U (an edge
with no constraint), or a NE (an actual "not-equal" edge in the graph) since
these are the only three possible edges in such problems.

The files do not contain a complete program, but simply contain functions which
are to be compiled and accessed as a library.  See the explanations of the
functions below along with a sample.  Note that to use the library correctly,
the "global.h" file must be included in all files which use its information
(such things as functions calls, data structures, etc.).  In addition, the
"srandom" function must be issued before calling the generate routine.

Note that most of the backtracking routines below are based on Prosser's paper
involving constraint satisfaction solving routines.



Files
=====

FC-GBJ.c        Forward checking with graph-based backjumping solving routine.
FC-arc.c        Forward checking with arc consistency solving routine.
backtrack.c     Generic backtracking access function.
generate.c      Generate graph-coloring problems to solve.
global.h        Type, function, and macro definitions.
process.c       Sample function for processing network solution.
timer.c         Routines to control program timers and stopwatches.
variable.c      Routines to order the variables according to a "degree"
                   heuristic.



Solving Methods
===============

Only two specialized solving methods have been created:

1) Forward checking with graph-based backjumping (FC-GBJ).  Defined by Prosser
   in research report.  Forward checking is truncated in that the current
   variable instantiated is compared with all future variables to see which
   domain values can be eliminated from the future variables.  Graph-based
   backjumping jumps past variables while backtracking whose instantiations
   would not affect the results of some inconsistency.

2) Full arc consistency forward checking with simple backtracking (FC-arc).
   Forward checking performs full arc consistency on future variables whenever
   the current variable is instantiated.  Simple backtracking is used since it
   too difficult to determine which point to back up to with full arc
   consistency.



Variable Ordering Heuristics
============================

Only one variable ordering heuristic is available.  It orders the variables
according to the "degree" heuristic.  Since the other two heuristics produce
the same results on graph-coloring problems.  In addition, the variables are
simply sorted, thus no other ordering techniques are provided.



Available Functions
===================

Available Functions
-------------------
1) backtrack(method, C, n, k, solution, found) to solve the problem.
2) generate(C, n, p) to generate graph coloring problems.
3) order_variables(C, n) to order the variables.
4) process_solution(C, n, solution) to process the solution found.
5) start_time(type, limit) to start the timer and stopwatch.
6) stop_time(type) to retrieve the time used.

Stop time returns a double which can then be used.
The meaning of the variables are as follows:
        method = backtracking method to use (either FC_GBJ or FC_arc)
        C = constraint network of type "NETWORK"
        n = number of variable in network
        k = number of values in each of the domains
        solution = solution to problem (of type "SOLUTION")
        found = integer passed by address which indicates whether a solution
                was found or not
        p = proportion of non-trivial edges in the problem (an integer
            representing a percentage)
        type = type of time (REAL or VIRTUAL)
        limit = timer limit (in seconds and given as an integer)


Other Global Information
------------------------
A variable called "checks" which maintains the number of consistency checks
performed by the backtracking routine.

Sample Main Program
===================
#include "global.h"

main()
{
    NETWORK C;
    SOLUTION solution;
    int found;

    srandom(0);
    generate(C, 50, 10);
    start_time(VIRTUAL, 600);
    order_variables(C, 50);
    backtrack(FC_arc, C, 50, 4, solution, &found);
    if (found)
        printf("time = %1.2f; cc = %1d\n", stop_time(REAL), checks);
}
