Galliwasp Files

Galliwasp 1.3.0 -- Goal-Directed Answer Set Programming
=======================================================

Project page: <http://www.utdallas.edu/~kbm072000/galliwasp/>

By [Kyle Marple](kbm072000@utdallas.edu).

Description
-----------

Galliwasp is a goal-directed answer set solving system. It accepts grounded
answer set programs in either normal logic or smodels format and finds produces
partial answer sets (if the program has an answer set) using a top-down
execution algorithm.

The software consists of two parts: the compiler and the interpreter. An ASP
grounder, such as lparse or gringo 4.0, is required but not included. The
compiler is written in Prolog, while the interpreter is written in standard C.
It has been successfully built under Linux and Mac OS X using gcc and Windows
using MinGW.

License
-------

Galliwasp is distributed under GNU Public License, see the file LICENSE for
details.

Package Contents
----------------

This README should be part of a distribution containing the following files and
directories.

* CHANGES -- Changelog
* LICENSE -- GNU Public License
* Makefile -- The main Makefile for the project
* README -- This file
* VERSION -- Contains the current version.
* interpreter/ -- Source code directory for the interpreter
* compiler/ -- Source code directory for the compiler

Installation
------------

Building Galliwasp requires the GNU Compiler Collection (GCC), SWI Prolog, and
GNU make. It is also assumed that the commands 'gcc', 'swipl' and 'make', may
be used to invoke the three, respectively. Building has been tested using GCC
version 4.6.2, SWI-Prolog 64-bit version 6.3.3 and GNU make version 3.81.

To build the compiler and interpreter, simply type 'make' from the project
directory. This will create two executables, 'gw', the interpreter, and
'gwc', the compiler, which can then be moved as needed.

Grounding
---------

To execute a program, it must first be grounded. Simple programs may be
grounded by hand, but a third-party grounder will be needed for more complex
programs. The compiler has been tested with text input from
[lparse](http://www.tcs.hut.fi/Software/smodels/) and smodels input from lparse
and [gringo 4.0-rc2](http://potassco.sourceforge.net). Note that gringo's text
output differs substantially from that of lparse and is not currently supported.

The choice of both grounder and input format can affect the output and runtime
performance of the interpreter. In particular, the smodels input format can
change the order of goals in the program and some grounders may remove
literals from a program before Galliwasp has access to it. When compared to
equivalent text format programs, this can result in answer sets being produced 
in a different order, certain literals being omitted from answer sets, and
differing runtime performance.

Optionally, text format programs may contain a 'compute' statement, indicating
the number of solutions to compute and the query to execute if the interpreter
is run in automatic mode, e.g.

        compute N { q1,...,qn }.

where N is the number of solutions to compute and the list of literals in
braces forms the query.

Usage
-----

The compiler reads grounded problem instances from a given file and writes
them to either stdout or a file specified with the -o switch:

        gwc inputfile
        gwc inputfile -o output file

To see an overview of the compiler's command-line options, type

        gwc -?

Once a program has been compiled, the compiled version can be read by the
interpreter from stdin or a file, e.g.

        gwc inputfile | gw
        gw <compiledinput>

The interpreter can run in either automatic or interactive modes. Interactive
mode can only be used if the compiled program is read from a file rather than
stdin. To run in automatic mode, the program instance must contain a compute
statement, a non-empty NMR check, or at least one optimization statement. When
available, the interpreter will default to automatic mode. Otherwise, the
interpreter will run in interactive mode. The '-i' switch can be used to force
the interpreter to use interactive mode, ignoring the compute statement, if
present, e.g.

        gw -i <compiledinput>

For an overview of the available command-line options, type

        gw -h
or

        gw -?

When run in automatic mode, the interpreter will simply execute the query
given by the compute statement to find partial answer sets and print them,
stopping when the specified number of sets has been computed or no more sets
satisfying the query exist.

In interactive mode, the user will be presented with a prompt to enter a
query. For an overview of valid queries, enter 'help.' at the prompt. To exit
the interpreter when finished, enter 'exit.' at the prompt. After each answer
set has been printed, the user can enter '.' to accept the set and return to
the query prompt. Alternatively, the user can enter ';' to reject the set and
find the next one, if it exists. In this way,a user can find as many answer
sets as desired. Finally, entering 'h' at the prompt will give an overview of
both options.

Optimization Statements
-----------------------

As of version 1.2.1, optimization statements (minimization and maximization)
are supported. However, due to the implementation, the results may not always
be what one would expect. The handling of optimization statements is as follows.

* Optimization statements are executed first, before any goals in the query or
  NMR check.
* Statements are processed in the order they are encountered, first to last.
* Each statement yields the most optimal solution that the current partial
  answer set allows.

If an answer set exists for a program, the first answer set returned is
guaranteed to be optimal w.r.t. the first optimization statement in the program.
However, optimality w.r.t subsequent statements is not guaranteed. Furthermore,
if a solution count greater than 1 is specified, subsequent answer sets may be
less and less optimal.