|
Size: 16200
Comment: some polishing
|
← Revision 82 as of 2023-10-12 12:16:39 ⇥
Size: 0
Comment: Info moved to repository
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| 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. === macOS === The planner contains the necessary code to compile and run on macOS, but since we do not use this platform, we cannot promise that it works as well as Linux. When running serious experiments with macOS, 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 macOS 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 macOS and Windows are also available. If your platform is not supported by the planner but you think it would not be too difficult to support it, please let us know. 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. == 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 5.4 and Clang 3.9. For planner comparisons we recommend using the latest GCC since the produced code ran faster than clang 3.3 and other GCC versions in [[http://issues.fast-downward.org/issue859|our tests]] (we haven't yet tested the performance of Clang 3.4 and later). 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 cmake g++ mercurial make python}}} should be sufficient. === LP Solver === Some configurations require an LP solver to work. The planner will compile fine if there is no LP installed on the system, but trying to use the features that require an LP solver will generate an error message explaining what is missing. See [[LPBuildInstructions]] for instructions on how to set up an LP solver and tell Fast Downward about it. === Validator VAL === You can validate the found plans by passing {{{--validate}}} to the planner. This invokes VAL (https://github.com/KCL-Planning/VAL). Here are the steps for setting up VAL for the planner: {{{#!highlight bash sudo apt-get install g++ make flex bison git clone https://github.com/KCL-Planning/VAL.git cd VAL make clean # Remove old build artifacts and binaries. make # Add "validate" binary to a directory on your PATH. }}} ==== Building VAL on Windows ==== You will need to download [[http://sourceforge.net/projects/winflexbison/|Flex and Bison]]. ==== Building VAL on macOS ==== If your compiler doesn't find flex or bison, your include directories might be in a non-standard location. In this case you probably have to specify where to look for includes and libraries in VAL's Makefile (probably {{{/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr}}}). === Additional dependencies on macOS === As of this writing, the planner appears to run without problems on macOS. However, we do not promise full support. === Dependencies on Windows === On Windows, you should install Visual Studio (we currently require Visual Studio 2017 [[https://visualstudio.microsoft.com/de/vs/older-downloads/]]), [[https://www.python.org/downloads/windows/|Python]], [[https://mercurial.selenic.com/wiki/Download|Mercurial]], and [[http://www.cmake.org/download/|CMake]]. During the installation of Visual Studio, the C++ 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: {{{#!highlight bash cd downward ./build.py}}} This will create our default build {{{release}}} in the directory {{{downward/builds}}}. Other predefined build types are {{{debug}}}, {{{releasenolp}}}, {{{debugnolp}}} and {{{minimal}}}. Calling {{{./build.py --debug}}} will create a default debug build (equivalent to {{{debug}}}). You can pass make parameters to {{{./build.py}}}, e.g., {{{./build.py --debug -j4}}} will create a debug build using 4 threads for compilation ({{{-j4}}}), and {{{./build.py translate}}} will only build the translator component. (Because the translator is implemented in Python, "building" it just entails copying its source code into the build directory.) By default, {{{build.py}}} uses all cores for building the planner. See [[#Manual_Builds]] for more complex builds. === Compiling on macOS === 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). === 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}}}). Also note that options are passed without {{{--}}}, e.g., {{{python build.py build=releasenolp}}}. 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 2017 you have to open a regular shell ({{{cmd}}}) and call the script {{{C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat x64}}} to set up the build environment. Alternatively, you can create a Visual Studio Project (see [[#Manual_Builds]]), 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 {{{release}}} 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}}} 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 15 2017"}}} This should generate a solution for Visual Studio 2017. Run this command in the command prompt with the environment variables loaded (i.e., execute the vsvarsall script). * {{{-G"XCode"}}} This should generate a project file for XCode. * 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.9}}} use: {{{#!highlight bash CC=clang-3.9 CXX=clang-3.9 cmake ../../src}}} Use full paths if the compiler is not found on the {{{PATH}}}, e.g., to force using the GNU compiler on macOS using !HomeBrew: /!\ Note that the following path is for GCC 4.8 which we no longer support. If you know the relevant path for a !HomeBrew version of GCC 5.4 or newer, please let us know. {{{#!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 build with the GNU compiler using !MacPorts: /!\ Note that the following path is for GCC 4.8 which we no longer support. If you know the relevant path for a !MacPorts version of GCC 5.4 or newer, please let us know. {{{#!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}}} If you use a configuration often, it might make sense to add an alias for it in {{{build_configs.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 [[Doc/SearchEngine|search engine]] with one or more [[Doc/Evaluator|evaluator specification]]s. == 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 [[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. 1. 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 at https://bitbucket.org/aibasel/downward-benchmarks, which includes all IPC domains (but not all ''formulations'' of all domains). 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 [[https://bitbucket.org/aibasel/downward-benchmarks/src/default/suites.py|suites.py]] script for your experiments. Here are the benchmark 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): {{{satisficing}}} * Admissible heuristics not supporting conditional effects and axioms (e.g. LM-Cut, iPDB): {{{optimal_strips}}} After cloning the repo, you can list the domains in the respective suites by doing: {{{#!highlight bash ./suites.py optimal_strips }}} You can use the resulting list of domains in your experiment scripts (see below). == Experiments with Fast Downward == The {{{Downward Lab}}} toolkit helps running Fast Downward experiments on large benchmark sets. → [[ScriptUsage|More information]] |