Differences between revisions 45 and 66 (spanning 21 versions)
⇤ ← Revision 45 as of 2014-10-22 19:57:03 →
Size: 8055
Editor: JendrikSeipp
Comment: mention new driver script instead of old bash script
← Revision 66 as of 2023-10-12 12:14:59 → ⇥
Size: 5142
Editor: GabiRoeger
Comment: Remove link to deleted page ObtainingAndRunningFastDownward
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
Running the planner is a three-step process as explained in Section 3 (pp. 202-203) of the [[http://www.jair.org/papers/paper1705.html|JAIR paper on Fast Downward]]. The following instructions show how to run these three steps, in sequence, assuming that the preprocessor and search component have been compiled and that you are currently located in the {{{src}}} directory.

If you want to run any of the planners based on Fast Downward that participated in IPC 2011, please also check IpcPlanners.

= Driver script =

We recommend using the {{{src/fast-downward.py}}} script for running Fast Downward. It supports running all three planner steps or a subset of them and automatically chooses the right steps depending on the given input. To see the list of options run		 To run Fast Downward, use the {{{fast-downward.py}}} driver script. At minimum, you need to specify the PDDL input files and search options consisting of a [[Doc/SearchAlgorithm|search algorithm]] with one or more [[Doc/Evaluator|evaluator specification]]s. The driver script has many options to do things like running portfolios, running only the translation component of the planner, using a non-standard build, running a plan validator and various other things. To see the complete list of options, run
Line 17: Line 11:
Below are the instructions for running individual steps without the driver script. If you want to run any of the planners based on Fast Downward that participated in IPC 2011, please also check IpcPlanners.
Line 19: Line 13:
== Translator == == Caveats ==
Line 21: Line 15:
{{{
translate/translate.py [DOMAIN] PROBLEM		 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.


== Different builds ==

Different builds of Fast Downward (e.g. release vs. debug) are placed in different directories by the build script. Hence, several builds can coexist and {{{fast-downward.py}}} must be told which build to use. By default, the {{{release}}} build is used, which is also the default build produced by {{{build.py}}}. To use a different build, pass {{{--build=<name>}}} to the driver script. The parameter {{{--debug}}} is an alias for {{{--build=debug --validate}}}.

'''Note on IDE projects (Visual Studio, XCode)''': You can use the CMake build system to generate a project for you favourite IDE. These projects are what CMake calls "multi-config generators", i.e., they are created without fixing the build configuration. At build time, the IDE decides whether to do a debug or release build and creates subdirectories in the output folder. Use the full path to the binaries as the value of {{{--build}}} (e.g., {{{--build=path/to/visual/studio/project/bin/Debug/}}}).

== Exit codes ==

The driver exits with 0 if no errors are encountered. Otherwise, it returns the exit code of the first component that failed. The exit codes are documented at ExitCodes.

== LP support ==

Features that use an LP solver have a command-line option `lpsolver` to switch between different solver types. See [[http://issues.fast-downward.org/issue752|issue752]] and [[http://issues.fast-downward.org/issue1076|issue1076]] for a discussion of the relative performance of CPLEX and !SoPlex.

Note that !SoPlex is not a MIP solver, so using it for configurations that require integer variables will result in an error. Please use CPLEX for such cases.


== Examples ==

=== A* search ===

{{{#!highlight bash
# landmark-cut heuristic
 ./fast-downward.py domain.pddl task.pddl --search "astar(lmcut())"

# iPDB heuristic with default settings
 ./fast-downward.py domain.pddl task.pddl --search "astar(ipdb())"

# blind heuristic
 ./fast-downward.py domain.pddl task.pddl --search "astar(blind())"
Line 25: Line 50:
 * `DOMAIN` (filename): PDDL domain file
 * `PROBLEM` (filename): PDDL problem file

If the domain file is not given, the planner will try to infer a likely name from the problem file name, using the conventions used at the various IPCs. (If in doubt if this will work for you, just try it out.)

Note: Creates a file called [[TranslatorOutputFormat|output.sas]].
== Preprocessor ==

{{{
preprocess/preprocess < OUTPUT.SAS
}}}

 * `OUTPUT.SAS` (filename): translator output

Note: Creates a file called [[PreprocessorOutputFormat|output]].

<<Anchor(search)>>
== Search component ==

{{{
search/downward OPTIONS < OUTPUT
}}}

 * `OPTIONS`: Examples below. See OptionSyntax and [[Doc/Overview]] for details.
 * `OUTPUT` (filename): preprocessor output

=== Exit codes ===

The list of '''exit codes''' for the search component is defined in [[http://hg.fast-downward.org/file/tip/src/search/utilities.h|src/search/utilities.h]] and explained below:

|| '''Code''' || '''Symbol''' || '''Meaning''' ||
|| 0 || EXIT_PLAN_FOUND || Solution found. ||
|| 1 || EXIT_CRITICAL_ERROR || Something went wrong that should not have went wrong (e.g. planner bug). ||
|| 2 || EXIT_INPUT_ERROR || Wrong command line options or SAS+ file. ||
|| 3 || EXIT_UNSUPPORTED || Requested unsupported feature. ||
|| 4 || EXIT_UNSOLVABLE || Task is provably unsolvable with current bound. Currently unused (see [[http://issues.fast-downward.org/issue377|issue377]]). ||
|| 5 || EXIT_UNSOLVED_INCOMPLETE || Search ended without finding a solution. ||
|| 6 || EXIT_OUT_OF_MEMORY || Memory exhausted. ||
|| 7 || EXIT_TIMEOUT || Timeout occured. Currently only returned by portfolios. ||
|| 8 || EXIT_TIMEOUT_AND_MEMORY || In portfolio configurations both timeouts and out-of-memory conditions occurred. ||

=== Examples ===

A* search:

{{{#!highlight bash
# landmark-cut heuristic (previously configuration "ou")
 ./fast-downward.py output --search "astar(lmcut())"

# merge-and-shrink heuristic with default settings (previously configuration "oa50000")
 ./fast-downward.py output --search "astar(merge_and_shrink())"

# blind heuristic (previously configuarion "ob")
 ./fast-downward.py output --search "astar(blind())"
}}}

Lazy greedy best first search with preferred operators and the queue alternation method:		 === Lazy greedy best-first search with preferred operators and the queue alternation method ===
Line 85: Line 54:
 ./fast-downward.py output \
    --heuristic "hff=ff()" --heuristic "hcea=cea()" \		  ./fast-downward.py domain.pddl task.pddl \
    --evaluator "hff=ff()" --evaluator "hcea=cea()" \
Line 91: Line 60:
 ./fast-downward.py output \
    --heuristic "hff=ff()" \
    --search "lazy_greedy(hff, preferred=hff)" \		  ./fast-downward.py domain.pddl task.pddl \
    --evaluator "hff=ff()" \
    --search "lazy_greedy([hff], preferred=[hff])" \
Line 97: Line 66:
 ./fast-downward.py output \
    --heuristic "hcea=cea()" \
    --search "lazy_greedy(hcea, preferred=hcea)" \		  ./fast-downward.py domain.pddl task.pddl \
    --evaluator "hcea=cea()" \
    --search "lazy_greedy([hcea], preferred=[hcea])" \
Line 103: Line 72:
Q: Is it possible to make the planner behave like "old" LAMA (the IPC 2008 version)?

A: We recommend against doing that and suggest you run the planner in "LAMA 2011 mode" instead (see next question). Still, here is the information for a LAMA-2008-like configuration:

The following configuration has all the ingredients of LAMA: it uses the landmark and FF heuristics in a lazy alternation search with preferred operators for both heuristics, uses iterated search with the appropriate set of options, and performs LAMA's +1 action cost adjustment on the heuristic for problems with non-unit-cost actions. It also uses the same mechanism for computing landmarks as LAMA. (There are, however, a number of implementation differences that make the behaviour of the planner different from original LAMA, e.g. slightly different tie-breaking in the FF heuristic computation.)		 === LAMA 2011 ===
Line 110: Line 75:
./fast-downward.py output \
       --heuristic "hlm=lmcount(lm_rhw(reasonable_orders=true,lm_cost_type=2,cost_type=2),pref=true)"
       --heuristic "hff=ff()"
       --search "iterated([lazy_greedy([hff,hlm],preferred=[hff,hlm]),
                           lazy_wastar([hff,hlm],preferred=[hff,hlm],w=5),
                           lazy_wastar([hff,hlm],preferred=[hff,hlm],w=3),
                           lazy_wastar([hff,hlm],preferred=[hff,hlm],w=2),
                           lazy_wastar([hff,hlm],preferred=[hff,hlm],w=1)],
                          repeat_last=true)"		  ./fast-downward.py --alias seq-sat-lama-2011 domain.pddl task.pddl
Line 121: Line 78:
The following is the corresponding call to just find a first solution (i.e., not doing iterated search):

{{{
 ./fast-downward.py output \
        --heuristic "hlm=lmcount(lm_rhw(reasonable_orders=true,lm_cost_type=2,cost_type=2),pref=true)"
        --heuristic "hff=ff()"
        --search "lazy_greedy([hlm, hff], preferred=[hlm, hff])"
           
}}}

Q: What do I need to do to run LAMA 2011?

All planners in the Fast Downward family that participated in IPC 2011 use exactly the same code and only differ in the command-line options used for the search component of the planner. LAMA 2011 is a bit special in that it uses two different parameter settings depending on whether the input planning task uses unit-cost actions only or general action costs. To enable this automatic switching, run the planner with:

{{{
 ./fast-downward.py --alias seq-sat-lama-2011 output
}}}

To find out which actual search options this corresponds to, check the source code of the {{{src/driver/aliases.py}}} module. Please also check the comments below on 32-bit vs. 64-bit mode.		 runs the "LAMA 2011 configuration" of the planner. (Note that this is not really the same as "LAMA 2011" as it participated at IPC 2011 because there have been bug fixes and other changes to the planner since 2011. See IpcPlanners for more information.) To find out which actual search options the LAMA 2011 configuration corresponds to, check the source code of the {{{src/driver/aliases.py}}} module.
Line 142: Line 81:
== 32-bit mode or 64-bit mode? == == 64-bit mode ==
Line 144: Line 83:
Our current codebase (as of November 2011) differs from the IPC versions of our planners in one way: by default, planner executables are compiled in 32-bit mode, while 64-bit was used at IPC 2011. The main differences between 32- vs. 64-bit mode are as follows:

 * 64-bit mode is faster than 32-bit mode (in our limited experiments typically by a factor of ~1.1)
 * 64-bit mode needs more memory than 32-bit mode (in our limited experiments typically by a factor of ~1.5)
 * 64-bit mode can use essentially unbounded amounts of memory, while 32-bit mode can only use 3 GB of user space memory (on typical Linux systems -- numbers may differ on other operating systems and depending on kernel options)

In our experiments, the memory advantage of 32-bit mode tends to outweigh the speed disadvantage, which is why we enable 32-bit mode by default. See http://issues.fast-downward.org/issue213 for details. However, for memory limits substantially beyond 4 GB, you should use 64-bit mode due to the address space limitations of 32-bit mode.

To enable 64-bit, compile the planner with the option {{{DOWNWARD_BITWITH=64}}}, e.g. by running
{{{
./build_all distclean
./build_all DOWNWARD_BITWIDTH=64
}}}
in the {{{src}}} directory. (If VAL is not currently compiled, the first line may give you an error, which you can ignore.)		 Older planner versions built the planner in 32-bit mode by default because of lower memory consumption. As part of the meta issue [[http://issues.fast-downward.org/issue213|issue213]] we decreased the memory consumption of 64-bit builds to the point where there should be no difference between 32- and 64-bit builds for most configurations. Therefore, we use the native bitwidth of the operating system since January 2019.

Back to HomePage.

Usage

To run Fast Downward, use the fast-downward.py driver script. At minimum, you need to specify the PDDL input files and search options consisting of a search algorithm with one or more evaluator specifications. The driver script has many options to do things like running portfolios, running only the translation component of the planner, using a non-standard build, running a plan validator and various other things. To see the complete list of options, run 

./fast-downward.py --help

If you want to run any of the planners based on Fast Downward that participated in IPC 2011, please also check IpcPlanners.

Caveats

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.

Different builds

Different builds of Fast Downward (e.g. release vs. debug) are placed in different directories by the build script. Hence, several builds can coexist and fast-downward.py must be told which build to use. By default, the release build is used, which is also the default build produced by build.py. To use a different build, pass --build=<name> to the driver script. The parameter --debug is an alias for --build=debug --validate.

Note on IDE projects (Visual Studio, XCode): You can use the CMake build system to generate a project for you favourite IDE. These projects are what CMake calls "multi-config generators", i.e., they are created without fixing the build configuration. At build time, the IDE decides whether to do a debug or release build and creates subdirectories in the output folder. Use the full path to the binaries as the value of --build (e.g., --build=path/to/visual/studio/project/bin/Debug/).

Exit codes

The driver exits with 0 if no errors are encountered. Otherwise, it returns the exit code of the first component that failed. The exit codes are documented at ExitCodes.

LP support

Features that use an LP solver have a command-line option lpsolver to switch between different solver types. See issue752 and issue1076 for a discussion of the relative performance of CPLEX and SoPlex.

Note that SoPlex is not a MIP solver, so using it for configurations that require integer variables will result in an error. Please use CPLEX for such cases.

Examples

   1 # landmark-cut heuristic
   2  ./fast-downward.py domain.pddl task.pddl --search "astar(lmcut())"
   3 
   4 # iPDB heuristic with default settings
   5  ./fast-downward.py domain.pddl task.pddl --search "astar(ipdb())"
   6 
   7 # blind heuristic
   8  ./fast-downward.py domain.pddl task.pddl --search "astar(blind())"

Lazy greedy best-first search with preferred operators and the queue alternation method

   1 ## using FF heuristic and context-enhanced additive heuristic (previously: "fFyY")
   2  ./fast-downward.py domain.pddl task.pddl \
   3     --evaluator "hff=ff()" --evaluator "hcea=cea()" \
   4     --search "lazy_greedy([hff, hcea], preferred=[hff, hcea])" \
   5            
   6 
   7 ## using FF heuristic (previously: "fF")
   8  ./fast-downward.py domain.pddl task.pddl \
   9     --evaluator "hff=ff()" \
  10     --search "lazy_greedy([hff], preferred=[hff])" \
  11            
  12 
  13 ## using context-enhanced additive heuristic (previously: "yY")
  14  ./fast-downward.py domain.pddl task.pddl \
  15     --evaluator "hcea=cea()" \
  16     --search "lazy_greedy([hcea], preferred=[hcea])" \
  17

LAMA 2011

 ./fast-downward.py --alias seq-sat-lama-2011 domain.pddl task.pddl

runs the "LAMA 2011 configuration" of the planner. (Note that this is not really the same as "LAMA 2011" as it participated at IPC 2011 because there have been bug fixes and other changes to the planner since 2011. See IpcPlanners for more information.) To find out which actual search options the LAMA 2011 configuration corresponds to, check the source code of the src/driver/aliases.py module.

64-bit mode

Older planner versions built the planner in 32-bit mode by default because of lower memory consumption. As part of the meta issue issue213 we decreased the memory consumption of 64-bit builds to the point where there should be no difference between 32- and 64-bit builds for most configurations. Therefore, we use the native bitwidth of the operating system since January 2019.

Other questions?

Please get in touch! See the HomePage for various contact options.

FastDownward: PlannerUsage (last edited 2023-10-12 12:14:59 by GabiRoeger)