Differences between revisions 3 and 41 (spanning 38 versions)
⇤ ← Revision 3 as of 2010-09-24 19:45:47 →
Size: 10817
Editor: MalteHelmert
Comment:
← Revision 41 as of 2016-01-31 14:11:48 → ⇥
Size: 15777
Editor: FlorianPommerening
Comment: Fixed dead link
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
This page is intended for people who are not core developers of the planner and want to use it in their own research, for example in order to: If you want to:
Line 7: Line 7:
 * conduct experiments that compare other systems against Fast Downward
 * implement their own search algorithms or heuristics by building on the Fast Downward code		  * conduct experiments that compare other planners against Fast Downward, or
 * implement your own search algorithms or heuristics that build on Fast Downward
Line 10: Line 10:
Since we don't currently consider the code to be in releasable shape, there is no "official" code distribution of the planner available at the moment. We can still give you access to the planner, but it's important that you be aware of some issues with the current codebase. then this page is for you.
Line 12: Line 12:
/!\ Note on running LAMA: As of this writing, most parts of LAMA have been (re-)integrated into the Fast Downward codebase, but there are still some important features and optimizations missing. If the reason why you want to access the Fast Downward code is because you want to run experiments that compare against the LAMA planner, we strongly recommend downloading the older, but more stable LAMA distribution from [[http://www.informatik.uni-freiburg.de/~srichter/|Silvia Richter's homepage]] instead. Since we don't currently consider the code to be in releasable shape, there is no "official" code distribution of the planner available at the moment. You can still get access to the planner, but it's important that you are aware of some issues with the current codebase.

/!\ '''Important note: Make sure to completely read the [[#Caveats]] section below.'''

/!\ '''Note on running LAMA:''' As of 2011, LAMA has been merged back into the Fast Downward codebase. "LAMA 2011", the version of LAMA that participated in IPC 2011, is Fast Downward with a particular set of command-line arguments. Since LAMA 2011 greatly outperformed LAMA 2008 in the competition, we strongly encourage you to use the current Fast Downward code when evaluating your planner against LAMA. See the following note.

/!\ '''Note on running IPC 2011 planners based on Fast Downward:''' After familiarizing yourself with the basics on this page, please check out IpcPlanners.

/!\ '''License:''' While our repository does not currently contain licensing information, the planner is made available under the GNU Public License (GPL). If you want to use the planner in any way that is not compatible with the GPL, you will have to get permission from us.

== Supported platforms ==

=== Linux ===

Linux is the main platform for which the planner is developed. All features should work without restrictions under Linux.

=== Mac OS X ===

The planner contains the necessary code to compile and run on Mac OS X, but since we do not use this platform, we cannot promise that it works as well as Linux. When running serious experiments with Mac OS X, we strongly suggest that you do at least some basic comparison to Linux to make sure that all results are in order and planner performance doesn't degrade. We appreciate bug reports and patches for this platform, including contributions to the documentation (e.g. installation instructions).

=== Windows ===

The same comments as for Mac OS X apply. Moreover, some diagnostic features, such as reporting memory used when the planner is terminated by a signal, are not supported under Windows. Due to library limitations setting time and memory limits and running portfolios is not supported under Windows. We appreciate bug reports and patches for this platform, including contributions to the documentation (e.g. installation instructions).
Line 16: Line 38:
In the following I will assume Ubuntu Linux or a similar system. If you use other kinds of Linux or other Unix-ish systems, you should be able to adapt the following steps to your setting. If you do not use a Unix-style system, you will probably not be able to compile the planner. In the following we will assume Ubuntu Linux or a similar environment. If you use other kinds of Linux or other Unix-ish systems, you should be able to adapt the following steps to your setting. Some basic instructions for Windows are also available. If you use a different system, you will probably not be able to compile the planner.
Line 18: Line 40:
The code is currently hosted in a Subversion repository. (A switch to Mercurial is planned for the near future.) If you haven't used Subversion before, you may want to have a look at the [[http://svnbook.red-bean.com/|excellent documentation available online]]. However, you don't really have to understand Subversion to use the planner, unless you also want to use our repository for your development efforts (see below). Since October 2010, the main development of the code takes place in a Mercurial repository. Before then, the code was hosted in a Subversion repository, which is still available. However, the trunk of the Subversion repository has been frozen (set to read-only) and will no longer receive updates or bug fixes. See LegacySubversionRepository if you need to access the old repository for some reason.

If you haven't used Mercurial before, you may want to have a look at the [[http://hgbook.red-bean.com/|excellent documentation available online]] (also available as a printed book published by O'Reilly Media). However, you don't really have to understand Mercurial to use the planner. For those experienced with Mercurial or similar distributed version control systems, we currently use a [[http://mercurial.aragost.com/kick-start/en/tasks|"single-pusher" task-based workflow with a single pusher]] for the Fast Downward repository. If you want to contribute to Fast Downward, the recommended way is to set up a clone of the master repository (e.g. on [[http://www.bitbucket.org|Bitbucket]]) and provide a link to it in our [[http://issues.fast-downward.org|issue tracker]] so that we can pull from it.
Line 22: Line 46:
To obtain and build the planner, you will need a non-ancient version of Subversion, a reasonably modern version of the GNU C++ compiler and the usual build tools such as GNU make. To run the planner, you will also need a reasonably modern version of Python 2.x ('''not''' Python 3.x!). These dependencies are typically satisfied by default on systems used to develop code. If not, {{{
sudo apt-get install subversion g++ make python}}}		 To obtain and build the planner, you need any version of Mercurial, a C++11 compiler, CMake and GNU make. We have successfully compiled the planner with GCC 4.8 and Clang 3.3/3.4. For planner comparisons we recommend using GCC 4.8 since the produced code runs faster than Clang 3.3's code on the included IPC planning benchmarks (we haven't yet tested the performance of Clang 3.4 and later). For the validator, VAL, you will need flex and bison. To run the planner, you also need Python 2.7 or Python >= 3.2. These dependencies are often satisfied by default on development machines. If not, {{{
sudo apt-get install mercurial g++ make python flex bison cmake}}}
Line 26: Line 50:
== Getting the code == === Additional dependencies on 64-bit systems ===
Line 28: Line 52:
To get access to the planner, <<MailTo(helmert@informatik.uni-freiburg.de, send me an email)>>. I will then add you to the list of people with access to the Subversion repository that hosts the code, and you will receive an automated email with instructions on how to set up your system to allow checking out the code. If you are using an x64 system, you will probably also need to run {{{
sudo apt-get install g++-multilib}}}
Line 30: Line 55:
The email will tell you to use the command {{{
svn checkout svn+ssh://downward DIRNAME}}} for the actual check-out, which is not a good command to use since it would check out all the (many) branches of the code, with multiple copies of the benchmark suite etc. Instead, I recommend you use the command {{{
svn checkout svn+ssh://downward/trunk DIRNAME}}} to only check out the trunk version of the code (i.e., the main line of current development).		 === Additional dependencies on Mac OS X ===

As of this writing, the planner appears to run without problems on Mac OS X. However, we do not promise full support.

=== Dependencies on Windows ===

On Windows, you should install Visual Studio (we tested with the free [[https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx|VS 2013 Express Community Edition]]), [[http://sourceforge.net/projects/winflexbison/|Flex, Bison]], [[https://www.python.org/downloads/windows/|Python]], [[https://mercurial.selenic.com/wiki/Download|Mercurial]], and [[http://www.cmake.org/download/|CMake]]. If you use Visual Studio 2015, make sure to install the C++ compiler. The compiler is not installed by default, but the IDE will prompt you to install it when you create a new C++ project.


== Obtaining the code ==

The command {{{
hg clone http://hg.fast-downward.org DIRNAME}}}
will create a clone of the Fast Downward master repository in directory {{{DIRNAME}}}. The directory is created if it does not yet exist. In the following, we assume that you used {{{downward}}} as the {{{DIRNAME}}}.
Line 36: Line 72:
The following assumes that you have checked out the planner trunk into directory {{{WORKING-COPY}}}. To first build the planner, run: To build the planner for the first time, run:
Line 38: Line 74:
cd WORKING-COPY
Line 40: Line 75:
./build_all}}} ./build.py}}}
Line 42: Line 77:
If you later make changes to the planner, it is preferable to use {{{make}}} in the different subdirectories of {{{downward}}} instead of rerunning {{{build_all}}} since you'll usually only work on one part of the planner at a time. This will create our default build {{{release32}}} in the directory {{{downward/builds}}}. Other predefined build types are {{{debug32}}}, {{{release64}}}, and {{{debug64}}}. (Please see [[PlannerUsage#64bit]] for caveats for 64-bit planners.) Calling {{{./build.py --debug}}} will create a default debug build (equivalent to {{{debug32}}}). You can pass make parameters to {{{./build.py}}}, e.g., {{{./build.py --debug downward -j4}}} will create a debug build of just the planner component (no preprocessor, translator or VAL), and use 4 threads for compilation ({{{-j4}}}).

See [[#Manual_Builds]] for more complex builds.

=== Compiling on Mac OS X ===

Fast Downward should compile with the GNU C++ compiler and {{{clang}}} with the same instructions described above. In case your system compiler does not work for some reason, you will need to install the GNU compiler (if not already present) and tell CMake which compiler to use (see #ManualBuilds).

If you get the following confusing log messages, your include directories might be in a non-standard location:
{{{#!highlight bash
-- Found BISON: /usr/bin/bison (found version "3.0.2")
-- Found FLEX: /usr/bin/flex (found version "2.5.35")
FLEX or BISON where not found, so VAL won't be build.
}}}

IN this case you also have to use a manual build and tell CMake where to look for includes and libraries using the parameter {{{-DCMAKE_PREFIX_PATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr}}}.

=== Compiling on Windows ===

Windows does not interpret the shebang in python files, so you have to call {{{build.py}}} as {{{python build.py}}} (make sure python is on your {{{PATH}}}).
The steps above should work if you execute them in the developer console of Visual Studio which will use {{{nmake}}} and {{{cl}}} for the build. For Visual Studio 2013 there should be a shortcut for {{{x86 native}}} in {{{C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\Tools\Shortcuts}}}. For Visual Studio 2015 you have to open a regular shell ({{{cmd}}}) and call the script {{{C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\Tools\VsDevCmd.bat}}} to set up the build environment.

Alternatively, you can create a Visual Studio Project (see [[#ManualBuilds]]), open it in Visual Studio and build from there. Visual Studio will create its binary files in subdirectories of the project that our driver script currently does not recognize. If you build with Visual Studio, you will have to run the individual components of the planner yourself.

== Manual Builds ==

The {{{build.py}}} script only creates a directory and calls {{{cmake}}} and {{{make}}}. To do these steps manually, run:
{{{#!highlight bash
mkdir -p builds/mycustombuild
cd builds/mycustombuild
cmake ../../src CMAKE_OPTIONS
make}}}

where {{{CMAKE_OPTIONS}}} are the options used to configure the build (see below). Without options, this results in the {{{release32}}} build. (Use {{{--build mycustombuild}}} in the {{{fast-downward.py}}} script to select this build when running the planner.)

You can use a CMake GUI to set up all available options. To do so, on Unix-like systems replace the call to {{{cmake}}} by {{{ccmake}}} ({{{sudo apt-get install cmake-curses-gui}}}). On Windows, open the CMake GUI and enter the paths there.

Possible options to configure the build include:
  * {{{-DPLUGIN_BLIND_SEARCH_HEURISTIC_ENABLED=False}}}
    Switch off the blind heuristic.
    See {{{src/search/FastDownwardPlugins.cmake}}} for other plugins.
  * {{{-DCMAKE_BUILD_TYPE=DEBUG}}}
    Other build types are: {{{RELEASE}}} (default) and {{{PROFILE}}}
  * {{{-DALLOW_64_BIT=YES}}}
    If you want to do a 64-bit compile, you might also have to set up your compiler in the right way, e.g., with {{{-DCMAKE_CXX_FLAGS="-m64"}}}. Please see [[PlannerUsage#64bit]] for caveats for 64-bit planners.

You can also generate makefiles for other build systems (such as ninja) or generate project files for most IDEs:
  * {{{-GNinja}}}
    Use {{{ninja}}} instead of {{{make}}} in step 4.
  * {{{-G"NMake Makefiles"}}}
    Windows command line compile. Open the x86 developer shell for your compiler
    and then use {{{nmake}}} instead of {{{make}}} in step 4.
  * {{{-G"Visual Studio 12 2013"}}}
    This should generate a solution for Visual Studio 2013. Also run this command in the x86 developer shell.
  * {{{-G"XCode"}}}
    This should generate a project file for XCode. On 64-bit systems, you might have to add the parameter {{{-DCMAKE_OSX_ARCHITECTURES=i386}}} to force a 32 bit build.
  * Run {{{cmake}}} without parameters to see which generators are available on your system.

You can also change the compiler/linker by setting the environment variables {{{CC}}}, {{{CXX}}} and {{{LINKER}}}.
For example, to compile with {{{clang-3.5}}} use:
{{{#!highlight bash
CC=clang-3.5 CXX=clang-3.5 cmake ../../src}}}
Use full paths if the compiler is not found on the {{{PATH}}}, e.g., to force using the GNU compiler on Mac OS X using !HomeBrew:
{{{#!highlight bash
CXX=/usr/local/Cellar/gcc48/4.8.3/bin/g++-4.8 CC=/usr/local/Cellar/gcc48/4.8.3/bin/g++-4.8 LINKER=/opt/local/bin/g++-mp-4.8 cmake ../../src}}}
The final example creates a 64-bit build with the GNU compiler using !MacPorts:
{{{#!highlight bash
CXX=/opt/local/bin/g++-mp-4.8 CC=/opt/local/bin/gcc-mp-4.8 LINKER=/opt/local/bin/g++-mp-4.8 cmake ../../src -DALLOW_64_BIT=YES}}}

If you use a configuration often, it might make sense to add an alias for it in {{{build.py}}}.
Line 46: Line 152:
For basic instructions on how to run the planner, see PlannerUsage. The search component of the planner accepts a host of different options with widely differing behaviour. At the very least, you will want to choose a SearchEngine with one or more [[HeuristicSpecification]]s. For basic instructions on how to run the planner including examples, see PlannerUsage. The search component of the planner accepts a host of different options with widely differing behaviour. At the very least, you will want to choose a [[Doc/SearchEngine|search engine]] with one or more [[Doc/Heuristic|heuristic specification]]s.
Line 52: Line 158:
 1. You are working with the most recent version of the development branch of the code, which of course is a '''moving target'''. Things can break or degrade with every commit. Typically they don't, but if they do, don't be surprised. We are working on a proper release, but we are not there yet. (For details, see [[http://issues.fast-downward.org/issue?%40search_text=&title=&%40columns=title&keyword=1&id=&%40columns=id&creation=&activity=&%40columns=activity&%40sort=activity&priority=&%40group=priority&status=-1%2C1%2C2%2C3%2C4%2C5%2C6%2C7&%40columns=status&%40pagesize=50&%40startwith=0&%40action=search|the list of outstanding issues for release 1.0 of the planner]].
 1. There are '''known bugs''', especially with the translator component. To find out more, check out [[http://issues.fast-downward.org|our issue tracker]]. The planner has only really been tested with IPC domains, and even for those it does not work properly with all formulations of all domains. See the list of "known good domains" below.
 1. We have recently integrated various branches of the code, and this has led to a '''performance degradation''' in some cases. For example, we know that there are issues with the landmark-cut heuristic (see [[http://issues.fast-downward.org/issue69]]). Other cases have not yet been properly tested for such performance degradations. Hence, before you report any performance results for the planner, please check them for plausibility by comparing them to our published results, and contact us if anything looks suspicious.
 1. '''Action costs''' as introduced for IPC-2008 are accepted by the planner, but currently most heuristics completely ignore them, which is often not what you want. For now, we recommend not conducting experiments with the IPC-2008 domains. (If you really want to, please get in touch so that we can tell you how your desired planner configuration handles action costs at the moment.)		  1. You are working with the most recent version of the development branch of the code, which is usually '''not thoroughly tested'''. Things can break or degrade with every commit. Typically they don't, but if they do, don't be surprised. We are working on a proper release, but we are not there yet. For more information, see [[http://issues.fast-downward.org/issue?%40search_text=&title=&%40columns=title&keyword=1&id=&%40columns=id&creation=&activity=&%40columns=activity&%40sort=activity&priority=&%40group=priority&status=-1%2C1%2C2%2C3%2C4%2C5%2C6%2C7&%40columns=status&%40pagesize=50&%40startwith=0&%40action=search|the list of outstanding issues for release 1.0 of the planner]].
 1. There are '''known bugs''', especially with the translator component. To find out more, check out [[http://issues.fast-downward.org|our issue tracker]]. The planner has only really been tested with IPC domains, and even for those it does not work properly with all formulations of all domains. For more information, see the section on [[#Known_good_domains]] below.
Line 57: Line 161:
search/downward --search lazy_greedy(ff(), preferred=(ff()))" < output}}} looks plausible, yet is hugely inefficient since it will compute the FF heuristic twice per state. See the examples on the PlannerUsage page to see how to call the planner properly. If in doubt, ask. ./fast-downward.py domain.pddl problem.pddl --search "lazy_greedy(ff(), preferred=ff())"}}} looks plausible, yet is hugely inefficient since it will compute the FF heuristic twice per state. See the examples on the PlannerUsage page to see how to call the planner properly. If in doubt, ask.
Line 61: Line 165:
There is a large collection of planning competition benchmarks in {{{trunk/benchmarks}}}, which includes all IPC domains before 2008 (but not all ''formulations'' of all domains). As of this writing, the domain collection does not include the IPC 2008 benchmarks. The planner is somewhat sensitive to non-STRIPS language constructs and will choke on some valid PDDL inputs. Moreover, many of the heuristics do not support axioms or conditional effects. Even worse, sometimes the translator will introduce conditional effects even though the original PDDL input did not contain them. (We are working on this.) There is a large collection of planning competition benchmarks in {{{downward/benchmarks}}}, which includes all IPC domains before 2014 (but not all ''formulations'' of all domains). As of this writing, the domain collection does not include the IPC 2014 benchmarks. The planner is somewhat sensitive to non-STRIPS language constructs and will choke on some valid PDDL inputs. Moreover, many of the heuristics do not support axioms or conditional effects. Even worse, sometimes the translator will introduce conditional effects even though the original PDDL input did not contain them. (We are working on this.)
Line 63: Line 167:
We recommend that you use the following "known working" sets of domains for your experiments (names of domains given as they exist in directory {{{trunk/benchmarks}}}): We recommend that you use the sets of domains that are predefined in the [[https://bitbucket.org/jendrikseipp/lab/src/tip/downward/suites.py|downward.suites]] module (part of the {{{lab}}} framework) for your experiments. The module contains many useful benchmark sets. Here are the suites that we usually use in the two most common settings:
Line 65: Line 169:
 * For heuristics supporting conditional effects and axioms (e.g. context-enhanced additive, FF, additive, causal graph): {{{airport}}}, {{{assembly}}}, {{{blocks}}}, {{{depot}}}, {{{driverlog}}}, {{{freecell}}}, {{{grid}}}, {{{gripper}}}, {{{logistics00}}}, {{{logistics98}}}, {{{miconic}}}, {{{miconic-fulladl}}}, {{{miconic-simpleadl}}}, {{{movie}}}, {{{mprime}}}, {{{mystery}}}, {{{openstacks}}}, {{{optical-telegraphs}}}, {{{pathways}}}, {{{philosophers}}}, {{{pipesworld-notankage}}}, {{{pipesworld-tankage}}}, {{{psr-large}}}, {{{psr-middle}}}, {{{psr-small}}}, {{{rovers}}}, {{{satellite}}}, {{{schedule}}}, {{{storage}}}, {{{tpp}}}, {{{trucks}}}, {{{zenotravel}}}. This set of domains is called the '''all suite'''.
 * For heuristics not supporting conditional effects and axioms (e.g. landmark-cut, merge-and-shrink): {{{airport}}}, {{{blocks}}}, {{{depot}}}, {{{driverlog}}}, {{{freecell}}}, {{{gripper}}}, {{{logistics00}}}, {{{logistics98}}}, {{{miconic}}}, {{{mprime}}}, {{{mystery}}}, {{{openstacks-strips}}}, {{{pathways-noneg}}}, {{{pipesworld-notankage}}}, {{{pipesworld-tankage}}}, {{{psr-small}}}, {{{rovers}}}, {{{tpp}}}, {{{trucks-strips}}}, {{{zenotravel}}}. This set of domains is called the '''LM-cut domains suite'''.		  * Inadmissible heuristics supporting conditional effects and axioms (e.g. context-enhanced additive, FF, additive, causal graph): {{{suite_satisficing_with_ipc11}}}
 * Admissible heuristics not supporting conditional effects and axioms (e.g. LM-Cut, iPDB): {{{suite_optimal_with_ipc11}}}
Line 68: Line 172:
(The second list is a subset of the first in terms of ''domains'' but not domain ''formulations'', as it uses the formulations {{{pathways-noneg}}} and {{{trucks-strips}}} instead of {{{pathways}}} and {{{trucks}}}.) After installing [[https://lab.readthedocs.org|lab]], you can list the domains in the respective suites by doing:
Line 70: Line 174:
== Scripts ==

The repository contains a set of scripts to automate experiments and conduct reports, but we don't currently feel they are in a shape to even start documenting them properly. However, you may want to play around with the scripts in the {{{scripts}}} and {{{new-scripts}}} directory to see if they do anything useful for you. However, no support is provided for them at the moment. Most scripts support a {{{--help}}} option.

One script that is very useful if you want to compare various configurations of the search component of the planner is {{{do_preprocess.py}}}, which runs the translator and preprocessor on a suite of benchmarks. Here are four ways of running it {{{!highlight bash
cd scripts
./do_preprocess.py grid:prob04.pddl
./do_preprocess.py pathways-noneg
./do_preprocess.py ALL
./do_preprocess.py LMCUT_DOMAINS		 {{{#!highlight python
from downward import suites
suites.suite_optimal_with_ipc11()
Line 82: Line 179:
The first of these will run the translator and preprocessor only on problem file {{{prob04.pddl}}} of the {{{grid}}} domain. The second will run them on all problem files for the {{{pathways-noneg}}} domain. The third and fourth will run them on all tasks from the all suite and LM-cut domains suite, respectively (see section on known good domains above). == Experiments with Fast Downward ==
Line 84: Line 181:
In all cases, the result files will be stored in a directory called {{{results}}} that is a sibling directory of {{{benchmarks}}}, {{{downward}}} and {{{scripts}}}.

In some domains, you will need a lot of memory to translate and preprocess the largest problem files (especially {{{psr-large}}} and {{{satellite}}}). We recommend 4 GB. If you have more memory and several cores, you can prepare several tasks in parallel with the option {{{-j}}}, which works the same way as in {{{make}}}: {{{!highlight bash
cd scripts
./do_preprocess.py -j 8 ALL}}}
will quickly preprocess all tasks in the all suite on a machine with 8 cores and 32 GB of RAM.

== Using our repository to develop your own branch of the code ==

TODO		 The {{{lab}}} python library has a module {{{downward}}} that helps running Fast Downward experiments on large benchmark sets. &rarr; [[ScriptUsage|More information]]

Back to the HomePage.

Obtaining and running Fast Downward

If you want to:

  • conduct experiments that compare other planners against Fast Downward, or
  • implement your own search algorithms or heuristics that build on Fast Downward

then this page is for you.

Since we don't currently consider the code to be in releasable shape, there is no "official" code distribution of the planner available at the moment. You can still get access to the planner, but it's important that you are aware of some issues with the current codebase.

/!\ Important note: Make sure to completely read the #Caveats section below.

/!\ Note on running LAMA: As of 2011, LAMA has been merged back into the Fast Downward codebase. "LAMA 2011", the version of LAMA that participated in IPC 2011, is Fast Downward with a particular set of command-line arguments. Since LAMA 2011 greatly outperformed LAMA 2008 in the competition, we strongly encourage you to use the current Fast Downward code when evaluating your planner against LAMA. See the following note.

/!\ Note on running IPC 2011 planners based on Fast Downward: After familiarizing yourself with the basics on this page, please check out IpcPlanners.

/!\ License: While our repository does not currently contain licensing information, the planner is made available under the GNU Public License (GPL). If you want to use the planner in any way that is not compatible with the GPL, you will have to get permission from us.

Supported platforms

Linux

Linux is the main platform for which the planner is developed. All features should work without restrictions under Linux.

Mac OS X

The planner contains the necessary code to compile and run on Mac OS X, but since we do not use this platform, we cannot promise that it works as well as Linux. When running serious experiments with Mac OS X, we strongly suggest that you do at least some basic comparison to Linux to make sure that all results are in order and planner performance doesn't degrade. We appreciate bug reports and patches for this platform, including contributions to the documentation (e.g. installation instructions).

Windows

The same comments as for Mac OS X apply. Moreover, some diagnostic features, such as reporting memory used when the planner is terminated by a signal, are not supported under Windows. Due to library limitations setting time and memory limits and running portfolios is not supported under Windows. We appreciate bug reports and patches for this platform, including contributions to the documentation (e.g. installation instructions).

Getting access to the planner

In the following we will assume Ubuntu Linux or a similar environment. If you use other kinds of Linux or other Unix-ish systems, you should be able to adapt the following steps to your setting. Some basic instructions for Windows are also available. If you use a different system, you will probably not be able to compile the planner.

Since October 2010, the main development of the code takes place in a Mercurial repository. Before then, the code was hosted in a Subversion repository, which is still available. However, the trunk of the Subversion repository has been frozen (set to read-only) and will no longer receive updates or bug fixes. See LegacySubversionRepository if you need to access the old repository for some reason.

If you haven't used Mercurial before, you may want to have a look at the excellent documentation available online (also available as a printed book published by O'Reilly Media). However, you don't really have to understand Mercurial to use the planner. For those experienced with Mercurial or similar distributed version control systems, we currently use a "single-pusher" task-based workflow with a single pusher for the Fast Downward repository. If you want to contribute to Fast Downward, the recommended way is to set up a clone of the master repository (e.g. on Bitbucket) and provide a link to it in our issue tracker so that we can pull from it.

Dependencies

To obtain and build the planner, you need any version of Mercurial, a C++11 compiler, CMake and GNU make. We have successfully compiled the planner with GCC 4.8 and Clang 3.3/3.4. For planner comparisons we recommend using GCC 4.8 since the produced code runs faster than Clang 3.3's code on the included IPC planning benchmarks (we haven't yet tested the performance of Clang 3.4 and later). For the validator, VAL, you will need flex and bison. To run the planner, you also need Python 2.7 or Python >= 3.2. These dependencies are often satisfied by default on development machines. If not, 

sudo apt-get install mercurial g++ make python flex bison cmake

should be sufficient.

Additional dependencies on 64-bit systems

If you are using an x64 system, you will probably also need to run 

sudo apt-get install g++-multilib

Additional dependencies on Mac OS X

As of this writing, the planner appears to run without problems on Mac OS X. However, we do not promise full support.

Dependencies on Windows

On Windows, you should install Visual Studio (we tested with the free VS 2013 Express Community Edition), Flex, Bison, Python, Mercurial, and CMake. If you use Visual Studio 2015, make sure to install the C++ compiler. The compiler is not installed by default, but the IDE will prompt you to install it when you create a new C++ project.

Obtaining the code

The command 

hg clone http://hg.fast-downward.org DIRNAME

will create a clone of the Fast Downward master repository in directory DIRNAME. The directory is created if it does not yet exist. In the following, we assume that you used downward as the DIRNAME.

Compiling the planner

To build the planner for the first time, run: 

   1 cd downward
   2 ./build.py

This will create our default build release32 in the directory downward/builds. Other predefined build types are debug32, release64, and debug64. (Please see PlannerUsage#64bit for caveats for 64-bit planners.) Calling ./build.py --debug will create a default debug build (equivalent to debug32). You can pass make parameters to ./build.py, e.g., ./build.py --debug downward -j4 will create a debug build of just the planner component (no preprocessor, translator or VAL), and use 4 threads for compilation (-j4).

See #Manual_Builds for more complex builds.

Compiling on Mac OS X

Fast Downward should compile with the GNU C++ compiler and clang with the same instructions described above. In case your system compiler does not work for some reason, you will need to install the GNU compiler (if not already present) and tell CMake which compiler to use (see #ManualBuilds).

If you get the following confusing log messages, your include directories might be in a non-standard location: 

   1 -- Found BISON: /usr/bin/bison (found version "3.0.2") 
   2 -- Found FLEX: /usr/bin/flex (found version "2.5.35") 
   3 FLEX or BISON where not found, so VAL won't be build.

IN this case you also have to use a manual build and tell CMake where to look for includes and libraries using the parameter -DCMAKE_PREFIX_PATH=/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr.

Compiling on Windows

Windows does not interpret the shebang in python files, so you have to call build.py as python build.py (make sure python is on your PATH). The steps above should work if you execute them in the developer console of Visual Studio which will use nmake and cl for the build. For Visual Studio 2013 there should be a shortcut for x86 native in C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\Tools\Shortcuts. For Visual Studio 2015 you have to open a regular shell (cmd) and call the script C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\Tools\VsDevCmd.bat to set up the build environment.

Alternatively, you can create a Visual Studio Project (see #ManualBuilds), open it in Visual Studio and build from there. Visual Studio will create its binary files in subdirectories of the project that our driver script currently does not recognize. If you build with Visual Studio, you will have to run the individual components of the planner yourself.

Manual Builds

The build.py script only creates a directory and calls cmake and make. To do these steps manually, run: 

   1 mkdir -p builds/mycustombuild
   2 cd builds/mycustombuild
   3 cmake ../../src CMAKE_OPTIONS
   4 make

where CMAKE_OPTIONS are the options used to configure the build (see below). Without options, this results in the release32 build. (Use --build mycustombuild in the fast-downward.py script to select this build when running the planner.)

You can use a CMake GUI to set up all available options. To do so, on Unix-like systems replace the call to cmake by ccmake (sudo apt-get install cmake-curses-gui). On Windows, open the CMake GUI and enter the paths there.

Possible options to configure the build include:

  • -DPLUGIN_BLIND_SEARCH_HEURISTIC_ENABLED=False

    • Switch off the blind heuristic.

      See src/search/FastDownwardPlugins.cmake for other plugins.

  • -DCMAKE_BUILD_TYPE=DEBUG

    • Other build types are: RELEASE (default) and PROFILE

  • -DALLOW_64_BIT=YES

    • If you want to do a 64-bit compile, you might also have to set up your compiler in the right way, e.g., with -DCMAKE_CXX_FLAGS="-m64". Please see PlannerUsage#64bit for caveats for 64-bit planners.

You can also generate makefiles for other build systems (such as ninja) or generate project files for most IDEs:

  • -GNinja

    • Use ninja instead of make in step 4.

  • -G"NMake Makefiles"

    • Windows command line compile. Open the x86 developer shell for your compiler

      and then use nmake instead of make in step 4.

  • -G"Visual Studio 12 2013"

    • This should generate a solution for Visual Studio 2013. Also run this command in the x86 developer shell.

  • -G"XCode"

    • This should generate a project file for XCode. On 64-bit systems, you might have to add the parameter -DCMAKE_OSX_ARCHITECTURES=i386 to force a 32 bit build.

  • Run cmake without parameters to see which generators are available on your system.

You can also change the compiler/linker by setting the environment variables CC, CXX and LINKER. For example, to compile with clang-3.5 use: 

   1 CC=clang-3.5 CXX=clang-3.5 cmake ../../src

Use full paths if the compiler is not found on the PATH, e.g., to force using the GNU compiler on Mac OS X using HomeBrew: 

   1 CXX=/usr/local/Cellar/gcc48/4.8.3/bin/g++-4.8 CC=/usr/local/Cellar/gcc48/4.8.3/bin/g++-4.8 LINKER=/opt/local/bin/g++-mp-4.8 cmake ../../src

The final example creates a 64-bit build with the GNU compiler using MacPorts: 

   1 CXX=/opt/local/bin/g++-mp-4.8 CC=/opt/local/bin/gcc-mp-4.8 LINKER=/opt/local/bin/g++-mp-4.8 cmake ../../src -DALLOW_64_BIT=YES

If you use a configuration often, it might make sense to add an alias for it in build.py.

Running the planner

For basic instructions on how to run the planner including examples, see PlannerUsage. The search component of the planner accepts a host of different options with widely differing behaviour. At the very least, you will want to choose a search engine with one or more heuristic specifications.

Caveats

Please be aware of the following issues when working with the planner, especially if you want to use it for conducting scientific experiments:

  1. You are working with the most recent version of the development branch of the code, which is usually not thoroughly tested. Things can break or degrade with every commit. Typically they don't, but if they do, don't be surprised. We are working on a proper release, but we are not there yet. For more information, see the list of outstanding issues for release 1.0 of the planner.

  2. There are known bugs, especially with the translator component. To find out more, check out our issue tracker. The planner has only really been tested with IPC domains, and even for those it does not work properly with all formulations of all domains. For more information, see the section on #Known_good_domains below.

  3. The search options are built with flexibility in mind, not ease of use. It is very easy to use option settings that look plausible, yet introduce significant inefficiencies. For example, an invocation like 

    ./fast-downward.py domain.pddl problem.pddl --search "lazy_greedy(ff(), preferred=ff())"

    looks plausible, yet is hugely inefficient since it will compute the FF heuristic twice per state. See the examples on the PlannerUsage page to see how to call the planner properly. If in doubt, ask.

Known good domains

There is a large collection of planning competition benchmarks in downward/benchmarks, which includes all IPC domains before 2014 (but not all formulations of all domains). As of this writing, the domain collection does not include the IPC 2014 benchmarks. The planner is somewhat sensitive to non-STRIPS language constructs and will choke on some valid PDDL inputs. Moreover, many of the heuristics do not support axioms or conditional effects. Even worse, sometimes the translator will introduce conditional effects even though the original PDDL input did not contain them. (We are working on this.)

We recommend that you use the sets of domains that are predefined in the downward.suites module (part of the lab framework) for your experiments. The module contains many useful benchmark sets. Here are the suites that we usually use in the two most common settings:

  • Inadmissible heuristics supporting conditional effects and axioms (e.g. context-enhanced additive, FF, additive, causal graph): suite_satisficing_with_ipc11

  • Admissible heuristics not supporting conditional effects and axioms (e.g. LM-Cut, iPDB): suite_optimal_with_ipc11

After installing lab, you can list the domains in the respective suites by doing: 

   1 from downward import suites
   2 suites.suite_optimal_with_ipc11()

Experiments with Fast Downward

The lab python library has a module downward that helps running Fast Downward experiments on large benchmark sets. → More information