hrussel / kec-sat-solver

Automatically exported from code.google.com/p/kec-sat-solver

HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH

                KECOSATS (Kelwin-Eleazar-Carlos Optimized SAT Solver)

HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH

Authors:
 Carlos Colmenares
 Eleazar Leal
 Kelwin Fernandez

Universidad Simón Bolívar. 
Caracas, Venezuela.

HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH

% This file is part of KECOSATS
% This README file was last updated Feb 2011.

README FILE
-----------
SUMMARY:

(I)     Software requirements
(II)    Compiling
(III)   Using the SAT solver's executable file 'kec_o_sat_s'
(III.1) The DIMACS CNF format
(III.2) Interpreting the 'kec_o_sat_s' output
(IV)    KECOSATS' directory structure
(V)     Further Information

HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH

--------------------------------------------------------------------------------
(I) Software requirements
--------------------------------------------------------------------------------

KECOSATS was writen and tested in several computers using either MAC OS X,
Debian GNU/Linux 6.0 (squeeze) or UBUNTU GNU/Linux 10.04 (Lucid Linx).

The program should run without any trouble in any Intel Pentium III (or
later, or similar) processor. The RAM memory requirements are directly
bounded to the size of the SAT instances given to the program.

For compiling the code, the next tools are necessary:
    (a) GNU Make 3.81 (or later, or equal)
    (b) gcc 4.4.5 (or later, or equal)
    (c) Doxygen version 1.7.1 (or later, or equal). NOTE: This tool is only
        necessary for generating the documentation (javadoc-like).

This program uses some system libraries and makes special system calls,
hence it is meant to be tested only in UNIX-like OS. Its behaviour in other
OS like Windows is unknown for the developers of the KECOSATS.
        
--------------------------------------------------------------------------------
(II) Compiling KECOSATS
--------------------------------------------------------------------------------

0.- Unzip or check out all the files in any directory "alpha"
    (Quotes for clarity, the directory may have any arbitrary name).
    It is necessary for the active user to have read, write and
    execute permissions on "alpha".

1.- Go inside KECOSATS's directory and execute the make file:
    E.G.:

    > cd /opt/kecosats
    > make

    ( where "alpha" = "/opt/kecosats" )

    Then the KECOSATS will be automatically compiled.

--------------------------------------------------------------------------------
(III)   Using the SAT solver's executable file 'kec_o_sat_s'
--------------------------------------------------------------------------------

0.- After compiling, an executable file 'kec_o_sat_s' will be created in the
    root directory of KECOSATS. Fore using KECOSATS its necessary to execute
    such file.

1.- For succesfully ussing the KECOSATS, some arguments need to be provided
    to the executable file, for detailed information about this options, just
    provide the '-h' flag to the executable. E.G.:

    > ./kec_o_sat_s -h

--------------------------------------------------------------------------------
(III.1) The DIMACS CNF format
--------------------------------------------------------------------------------

For providing SAT insances to the KECOSATS, the instance has to be written in
a file with the DIMACS CNF format. For further information about this format
go to:

    http://logic.pdmi.ras.ru/~basolver/dimacs.html

Several SAT instances with DIMACS CNF format can be found in the 'test'
directory.

--------------------------------------------------------------------------------
(III.2) Interpreting the 'kec_o_sat_s' output
--------------------------------------------------------------------------------

If the '-o <output_file>' flag is provided to the program, an assignment for
the formula's variables will be written in 'output_file' following the
following format:

If the formula is unsatisfiable:
    > The output file will contain a single line with the word "UNSAT" (quotes
      for clarity).

If the formula is satisfiable:
    > The first line of the output file will contain the string "1 0" (quotes
      for clarity)
    > N lines will follow, where N is the number of variables in the formula:
      The ith line will contain a single number, either "0", "1" or "-1":
      >> If the ith line contains a "0", for satisfying the formula, the ith
         variable needs to be assigned with a TRUE value
      >> If the ith line contains a "1", for satisfying the formula, the ith
         variable needs to be assigned with a FALSE value
      >> If the ith line contains a "-1", for satisfying the formula, the ith
         variable can be assigned with ANY value (either TRUE or FALSE).

--------------------------------------------------------------------------------
(IV) KECOSATS directoy structure
--------------------------------------------------------------------------------

The project is comprised of several files and directories, the puspose of the
directory is described below. Note: For an explanation of the purpose of each
file, consult either each file's header or the documentation generated by
doxygen.

    /-------> /src:     Contains the source code (.c) for each of the files
    |                   that comprise the KECOSATS.
    |
    |-------> /lib      Contains the headers (and procedures' documentation)
    |                   for each of the files that comprise the KECOSATS.
    |
    |-------> /bin      After compiling, the generated binary files (.o) are
root_dir                stored in this directory.
    |
    |-------> /doc      Contains both the documentation of the KECOSATS and the
    |                   doxygen documentation for the source code.
    |
    |-------> /test     Contains several test files for testing the KECOSATS.
    |                   In the subdirectory 'sudoku_tests' some sudoku test
    |                   cases can be found. 
    |
    \-------> /sudoku2sat   Contains an executable file that transform a sudoku
                            instance to a SAT instance, the output is generated
                            in DIMACS CNF format. For further information,
                            refer to the documentation of the code (inside that
                            directory) or the README_SUDOKU file

--------------------------------------------------------------------------------
(V) Further Information
--------------------------------------------------------------------------------

    The documentation of the KECSATS can be found in the 'doc' directory. Also
for generating the Doxygen documentation of the code (which will be stored in
the 'doc' directory), just execute the command 'make doc' in the root directory
of KECOSATS. E.G.:

    > cd /opt/kecosats
    > make doc

    If you are interested in KECOSATS or simply want to know any
information about its designers, feel free to send an email to any
of the following email addresses:

> [e-mail]
> [e-mail]
> [e-mail]