**************************** IMPORTANT NOTE ****************************

NOTE: This file almost certainly does not contain the information you
are looking for. It is a legacy README file that is no longer
accurate. We keep it around in case we want to use it as the basis for
some more up-to-date information some day. In the meantime, check out
http://www.fast-downward.org/ObtainingAndRunningFastDownward to get
started with Fast Downward.

**************************** IMPORTANT NOTE ****************************











This is the current "official" distribution of Fast Downward. Sorry
for the mess.

License: All code (c) copyright by Malte Helmert and/or Silvia
Richter. You may pass this on to your students or collaborators, but
you may not make it available on public websites or give it to other
people without asking for permission first (email to Malte Helmert
<helmert@informatik.uni-freiburg.de>). This is not because I like to
sit on my code in general but because I know it is buggy and
underdocumented and don't feel too well about it spreading.

Note: This distribution doesn't really reflect any of the developments
of the planner past 2004, such as any heuristics other than the
original CG and FF heuristics. (Or maybe it does, but then we have
forgotten to update this README file.) If you are interested in any of
the more recent work we did based on the original Fast Downward code
(h^cea, merge-and-shrink abstractions, Landmark-related things, ...),
please contact me. We're working on integrating all that, but that's
quite a major undertaking.


Structure
=========

Fast Downward runs in three separate phases: translation, knowledge
compilation, and search. These are partitioned into three separate
programs. The three directories "translate", "preprocess" and "search"
contain these three programs. As you might guess, the directory "doc"
contains some documentation.


Documentation
=============

Apart from this README file, four pieces of documentation are
available (all in the "doc" directory):

1. "fast-downward.pdf" is the JAIR paper [1] on Fast Downward. It
   contains a full description of the IPC4 version of the planner,
   except for the translation component, which is documented
   separately (see the following point).

   Some parts of the code have been removed in a cleanup effort after
   IPC4, so that not all planner configurations described in the paper
   are currently available. Specifically, the "G+P^+" configuration
   (causal graph heuristic with helpful transitions, using helpful
   actions iff no helpful transitions are available) and the "F"
   configuration (focused iterative-broadening search) are not
   available, and neither is the ability to run several configurations
   of the planner in parallel as done for the "FD" and "FDD"
   configurations at IPC4. If you need these features, please contact
   me and I will try to dig out the IPC4 version of the planner.

2. "translator.pdf" is the chapter of my PhD thesis [2] that describes
   the translation component. The description is somewhat idealized,
   as the actual implementation has some limitations in dealing with
   some ADL features. Still, the chapter provides a fairly good
   description of what the translator does (or should do, at any
   rate). If you need to cite this work, it's actually better to cite
   the AIJ paper on the translator [3] which I cannot provide here for
   copyright reasons. A preprint of that paper is available from my
   website.

3. "sas-format.txt" is a description of the translator output format.
   You will only need this if you want to use planning tasks in
   finite-domain representation (FDR tasks) within your own planner.

4. "pre-format.txt" is a description of the output format of the
   knowledge compilation component ("preprocess"). You will only need
   this if you want to use the preprocessed FDR task information
   within your own planner.


Build Instructions
==================

Parts of the planner are implemented in C++, and parts are implemented
in Python.

The C++ code was only tested under g++ and uses hash tables from the
original STL which are part of the g++ libraries but not of the C++
standard. So if you want to make the planner run under a different C++
environment, you will need to adjust the parts of the planner that use
these features.

On a standard Unix-ish system, just run "make" in this directory to
build the C++ components of the planner. The executables will be
placed in the respective directories. (If this does not work, simply
compile and link all the C++ source files you find in each directory.)

If the Makefile does not work for you or you have trouble compiling
the planner (e.g. due to the code's use of hash tables), I'd be happy
about any feedback on which problems you encountered and how you
addressed them.

The Python code is interpreted and thus does not need compilation.
However, you will need a Python interpreter, version 2.5 or newer, to
run it. If you are on a non-Unix system, you will probably need to
install Python by following the instructions at
http://www.python.org/. If you are on a Unix-ish system, check if the
correct version of Python is installed already by typing "python
--version" in a shell. It usually is. If you do not get an error
message and the reported Python version is in the 2.5 or 2.6 family,
you are fine. The translator will *not* work with Python 2.4 or older
or with Python 3.*, which is incompatible with the 2.* series. If you
only have an older version of Python (or none) installed, go ahead and
install a newer one with your Unix system's package manager (e.g. with
"aptitude install python2.6" on a Debian or Ubuntu system). Different
versions of Python can peacefully coexist, so this should not wreck
your system setup.


Running the Planner
===================

There are three steps to solving a planning task.

First, run:

   # translate/translate.py domain.pddl problem.pddl

   The translator which supports full propositional PDDL2.2, including
   ADL-style conditions and derived predicates. It has some bugs in
   ADL domains, though -- if you want to run it on the IPC4
   competition domains, try the formulations indicated in the JAIR
   paper [1] or you are likely to suffer crashes or other weird
   behaviour.

   The translator writes its result to a file called "output.sas",
   which serves as an input to the next phase, knowledge compilation.
   It also writes a file called "test.groups", which is some sort of
   translation key (see "sas-format.txt" in the documentation
   directory mentioned above). This second file is not needed by the
   planner, but might help you understand what the translated task
   looks like.

   It the translator also generates a file called "all.groups", then
   this documentation is out of date. Please contact us.

Second, run:

   # preprocess/preprocess < output.sas

   This will run the knowledge compilation component, writing its
   output to the file aptly named "output".

Finally, run one of:

   # search/search c    < output
   # search/search cC   < output
   # search/search cf   < output
   # search/search cCfF < output

   This runs the search component of the planner. On success, it will
   write a file called "sas_plan" containing the plan. Note that the
   dead-end detection routine described in the ICAPS 2004 paper [4]
   has been removed from the planner because the implementation has
   never been extended beyond STRIPS and we did not consider it
   important enough to upgrade and maintain it. Therefore, you cannot
   trust the planner when it says that a given task is unsolvable
   unless you use the option to include the FF heuristic ("f"), which
   is dead-end safe.

   The different invocations listed above correspond to the following
   configurations of the planner (using the names from page 232 of the
   JAIR paper [1]), in sequence: G, G+P, M, M+P. Other combinations
   are possible; the planner understands four options which can be
   combined in any way, but at least one heuristic ("c" or "f") must
   be used:

   c:  Use the causal graph heuristic.
   C:  Use helpful transitions ("preferred operators" of the causal
       graph heuristic).
   f:  Use the FF heuristic.
   F:  Use helpful actions ("preferred operators" of the FF
       heuristic).


Benchmarking
============

If you want to benchmark the planner, for example to compare it to
other planning systems, please note that the different configurations of
the search component have a huge impact on performance. Which options
work best varies across domains. If in doubt and not in a mood to
experiment, activate all features (use options "cCfF").


Questions and Feedback
======================

Please feel free to email me at helmert@informatik.uni-freiburg.de if
you have any questions, if you encounter bugs, or if there are any
issues regarding the planner that you would like to discuss.


References
==========

[1] Malte Helmert. The Fast Downward planning system.
    Journal of Artificial Intelligence Research, 26:191-246, 2006.

[2] Malte Helmert. Solving planning tasks in theory and practice.
    Ph.D. thesis, Albert-Ludwigs-Universitaet Freiburg, 2006.

    Revised version published as: Malte Helmert. Understanding
    Planning Tasks: Domain Complexity and Heuristic Decomposition.
    Volume 4929 of Lecture Notes in Artificial Intelligence.
    Springer-Verlag, Heidelberg, 2008.

[3] Malte Helmert. Concise finite-domain representations for PDDL
    planning tasks. Artificial Intelligence, 173:503-535, 2009.

[4] Malte Helmert. A planning heuristic based on causal graph
    analysis. In Shlomo Zilberstein, Jana Koehler and Sven Koenig
    (eds.), Proceedings of the Fourteenth International Conference on
    Automated Planning and Scheduling (ICAPS 2004), pp. 161-170.
