\section{Introduction}\label{sec:introduction}

The ``Potsdam Answer Set Solving Collection'' (Potassco)~\cite{potassco}
by now gathers a variety of tools for Answer Set Programming.
Among them, we find grounder \gringo, solver \clasp, and
combinations thereof within integrated systems \clingo\ and \iclingo.
All these tools are written in \texttt{C++} and published under GNU General Public License(s)~\cite{GNUgpl}.
Source packages as well as precompiled binaries for Linux and Windows are available at~\cite{potassco}.
For building one of the tools from sources,
please download the most recent source package and consult the
included \code{README} or \code{INSTALL} text file, respectively.
Please make sure that the platform to build on has the
required software installed.
If you nonetheless encounter problems in the building process,
please use the potassco mailing list 
\href{mailto:potassco-users@lists.sourceforge.net}{potassco-users@lists.sourceforge.net}
or consult the supporting pages at \href{http://potassco.sourceforge.net}{potassco.sourceforge.net}.

After downloading (and possibly building) a tool,
one can check whether everything works fine by invoking the tool
with flag \code{--version} (to get version information) or
with flag \code{--help} (to see the available command line options).
For instance, assuming that a binary called \gringo\ is in the path
(similarly, with the other tools),
the following command line calls should be responded by \gringo:
%
\begin{lstlisting}[numbers=none]
gringo --version
gringo --help
\end{lstlisting}
If grounder \gringo, solver \clasp, as well as integrated systems
\clingo\ and \iclingo\ are all available,
one usually provides the file names of input text files to either
\gringo, \clingo, or \iclingo, while the output of \gringo\ is
typically piped into \clasp.
Thus, the standard invocation schemes are as follows:
\begin{lstlisting}[numbers=none]
gringo  [ options | files ] | clasp [ options | number ]
clingo  [ options | files | number ]
iclingo [ options | files | number ]
\end{lstlisting}
Note that a numerical argument provided to either \clasp, \clingo, or \iclingo\
determines the maximum number of answer sets to be computed,
where \code{0} stands for ``compute all answer sets.''
By default, only one answer set is computed (if it exists).

This guide introduces the fundamentals of using
\gringo, \clasp, \clingo, and \iclingo.
In particular, it tries to enable the reader to benefit from them
by significantly reducing the ``time to solution'' on difficult problems.
The outline is as follows.
In Section~\ref{sec:quickstart},
an introductory example is given
that serves both as guideline on how to model problems using logic programs
and also as an example on how compact and concise the modeling language of \gringo\ is.
The probably most important part for a user, Section~\ref{sec:language},
is dedicated to the input languages of our tools,
where the joint input language of \gringo\ and \clingo\
claims the main share (later on, it is extended by \iclingo).
For illustrating the application of our tools,
three well-known example problems are solved in Section~\ref{sec:examples}.
Practical aspects are also in the focus of Section~\ref{sec:options} and~\ref{sec:error:warn},
where we elaborate and give some hints on the available command line options
as well as input-related errors and warnings that may be reported.
During the guide we forgo most of the theoretical background in favor
of small intuitive examples and informal descriptions.
%For a more theoretical background, the interested reader is referred
%to Appendix~\ref{sec:background} where technical details are covered.

For readers familiar with \lparse~\cite{lparseManual}
(a grounder that constitutes the traditional front end of solver \smodels~\cite{siniso02a}),
Appendix~\ref{sec:lparse}
% \comment{Appendix not updated yet}
lists the most prominent differences to our tools.
Otherwise, \gringo, \clingo, and \iclingo\ should accept most inputs recognized by \lparse,
while the input of solver \clasp\ can also be generated by \lparse\ instead of \gringo.
Throughout this guide, we provide quite a number of examples.
Many of them can actually be run, and instructions on how to accomplish this
(or sometimes meta-remarks)
are provided in margin boxes, where an occurrence of ``\code{\char`\\}''
usually means that a text line broken for space reasons is actually continuous.
After all these preliminaries, it is time to start our guided tour
through Potassco~\cite{potassco}.
We hope that you will find it enjoyable and helpful!

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "guide"
%%% End: 
